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Introduction 


1.1 Application Programming Interface 


This manual describes the application programming interface (API) of the 
Microsoft® Windows presentation manager. The API contains the func- 
tions, messages, data structures, data types, and files that application 
developers use to create programs that run with Windows. 


The API can be thought of as a set of tools which, when properly used, 
creates a Windows application that is portable across a variety of 
computers. 


1.2 Windows Features 


A Windows application can take advantage of a number of features 
provided by the API. These features include the following: 


e Shared display, memory, keyboard, mouse, and system timer 
e Data interchange with other applications 

e Device-independent graphics 

e Multitasking 


e Dynamic linking 


Windows allows applications, running simultaneously on the system, to 
share hardware resources; application developers do not need to write 
specific code to accomplish this complex task. 


The clipboard, another Windows feature, acts as a place for data inter- 
change between applications. The information sent between applications 
can be in the form of text, bitmaps, or graphic operations. Windows pro- 
vides a number of functions and messages that regulate the transmission 
of information with the clipboard. These functions and the corresponding 
messages are part of the window manager interface, one of three libraries 


in the API. 


Windows contains functions that an application can use for device- 
independent graphic operations. These functions create output that is 
compatible with raster displays and printers of varying resolution, as well 
as with a number of vector devices (plotters). These functions are part of 
the graphics device interface (GDI), the second of the three API libraries. 
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Windows provides multitasking, which means that several applications 
can run simultaneously. In order to achieve multitasking, Windows keeps 
only necessary code and data in memory. The functions that affect multi- 
tasking and memory management in general are part of the system ser- 
vices interface, the third API library. 


Because of the memory limitations imposed by DOS, it is important to 
keep applications as compact as possible. Windows accomplishes this com- 
paction through dynamic linking, which allows an application to load and 
execute a library of functions at run time. Only a single copy of a library 
is necessary, no matter how many applications access It. 


1.3. Window Manager Interface 


The window manager interface contains the functions that create, move, 
and alter a window, the most basic element in a Windows application. A 
window is a rectangular region that contains graphic representations of 
user input, input options, and system output. Figure 1.1 shows a collection 
of windows: 
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Figure 1.1 Overlapped Windows 
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Windows is a menu-driven environment; menus are the principal means 
of presenting options to a user from within an application. The functions 
that create menus, alter their contents, and obtain the status of menu 
items are also part of the window manager interface. Figure 1.2 shows the 
File menu, which depicts various actions that a user may select and that 
Windows will perform on a given file: 
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Figure 1.2 File Menu 


The window manager interface also contains functions that create system 
output. An example of this output is the dialog box that applications use 
to request user input and to display information. Figure 1.3 shows a win- 
dow that contains a dialog box: 


Control Pane] EY 
nstallation Setup Preferences 


Screen Colors 


Screen Backay ound 
Application Workspace 


Figure 1.3 Dialog Box 
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The window manager interface also contains messages and the functions 
that process them. A message is a special data structure that contains 
information about changes within an application. These changes include 
keyboard, mouse, and timer events, as well as requests for information or 
actions that an application should carry out. 


1.3.1 Window Manager Interface Function Groups 


The following list describes the function groups found in the window 
manager interface: 


Message functions Information functions 
Window-creation functions System functions 
Display and movement functions Clipboard functions 
Error functions Input functions 

Caret functions Hardware functions 
Cursor functions Painting functions 
Hook functions Dialog functions 
Property functions Scrolling functions 
Rectangle functions Menu functions 


1.4 Graphics Device Interface 


The graphics device interface (GDI) contains the functions that perform 
device-independent graphic operations within a Windows application. 
These functions create a wide variety of line, text, and bitmap output 
on a number of different output devices. GDI allows an application to 
create pens, brushes, fonts, and bitmaps for specific output operations. 
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Figure 1.4 shows a sample of text, line, and bitmap output from Microsoft 
Windows Paint, an application that was created with GDI functions: 
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Figure 1.4 Text, Line, and Bitmap Output 


1.4.1 Graphics Device Interface Function Groups 


The following list describes the function groups found in the graphics 
device interface (GDI): 


Device-context functions Ellipse and polygon functions 


Drawing-tool functions Bitmap functions 
Drawing-attribute functions Text functions 

Mapping functions Font functions 
Coordinate functions Metafile functions 
Region functions Printer-escape functions 
Clipping functions Environment functions 
Line-output functions System functions 
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1.5 System Services Interface 


The system services interface contains the functions that access code and 
data in modules, allocate and manage memory (both local and global), 
manage tasks, load program resources, translate strings from one charac- 
ter set to another, alter the Windows initialization file, assist in system 
debugging, carry out communications through the system’s I/O ports, 
create and open files, and create sounds using the system’s sound gen- 
erator. 


1.5.1 System Services Interface Function Groups 


The following list describes the function groups found in the system 
services interface: 


Module-manager functions Initialization-file functions 
Memory-manager functions Communication functions 
Task functions Sound functions 
Resource-manager functions Utility functions 
String-translation functions File I/O functions 
Atom-manager functions System functions 


1.6 Naming Conventions 


Many Windows functions have been named with a verb-noun model to 
help you remember and become familiar with the function. The function 
name indicates both what the function does (verb) and the target of its 
action (noun). All function names begin with an uppercase letter. If the 
name is composed of several words, each word begins with an uppercase 
letter and all words are adjoined ne spaces or underscore characters 
separate the words). Some examples of function names are shown below: 


Create Window 
RegisterClass 
SetMapMode 
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1.7 Parameter Names 


Most parameters and local variables have a lowercase prefix that indicates 
the general type of the parameter, followed by one or more words that 
describe the content of the parameter. The standard prefixes used in 
parameter and variable names are defined below: 


Prefix Meaning 


b Boolean (a nonzero value means true, zero means false} 
c Character (a one-byte value) 

dw Long (32-bit) unsigned integer 

f Bit flags packed into a 16-bit integer 

h 16-bit handle 

l Long (32-bit) integer 

lp Long (32-bit) pointer 

n Short (16-bit) integer 

p Short (16-bit) pointer 

pt z- and y-coordinates packed into an unsigned 32-bit integer 
rgb RGB color value packed into a 32-bit integer 

w Short (16-bit) unsigned integer 


If no lowercase prefix is given, the parameter is a short integer whose name 
is descriptive. 


Some examples of parameter and variable names are shown below: 
bIconic = ptXY 
fAction —_rgbColor 
hWnd Height 


lpString X 
nBytes Width 
pMsgq Y 
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1.8 Windows Calling Convention 


Windows uses the same calling convention used by Microsoft Pascal. 
Throughout this manual, this calling convention will be referred to as 
the Pascal calling convention. The Pascal calling convention entails 
the following: 


e Parameters are pushed onto the stack in the order in which they 
appear in the function call. 


e The code that restores the stack is part of the called function 
(rather than the calling function). 


This convention differs from the calling convention used in other lan- 
guages, such as C. In C, parameters are pushed onto the stack in reverse 
order, and the calling function is responsible for restoring the stack. 


When developing Windows applications in a language that does not ordi- 
narily use the Pascal calling convention, such as C, you must ensure that 
the Pascal calling convention is used for any function that is called by 
Windows. In C, this requires the use of the PASCAL keyword when the 
function is declared. 


1.9 Near and Far Pointers 


Windows uses near and far pointers to take advantage of Intel 8086 
and 8286 architecture. 


A near pointer is a short pointer (16 bits) that consists of an offset from 
one of the current segment register values. A far pointer is a long pointer 
(32 bits) that consists of a full segmented address; the segment address is 
in the high-order word, and the offset is in the low-order word. The default 
size of pointers in your program depends on the language and the memory 
model you are using. 


In some cases, Windows explicitly requires a far pointer. In particular, 
whenever you pass Windows a pointer to a function that will later be 
called back by Windows, the pointer must be a far pointer. This manual 
tells you whenever a far pointer is required. 


To obtain a far pointer when the default size of your pointer is near, you 


must explicitly declare the pointer to be a far pointer. See your language 
documentation for details on declaring far pointers. 
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1.10 Manual Overview 


This manual gives the Windows-application developer general as well as 
detailed information about Windows functions, messages, data types, and 
file formats. 


Chapter 1, “Introduction,” describes the application programming inter- 
face (API) and the interface function groups, and presents information 
about the organization and conventions used in this manual. 


Chapter 2, “Functions Overview,” categorizes functions in their related 
groups, provides brief descriptions of individual functions, and supplies 
additional information about particular function groups. This additional 
information includes definitions of new terms and descriptions of models 
that are unique to Windows. This chapter is designed to assist the applica- 
tion developer who is new to Windows or who has questions about a par- 
ticular group of Windows functions. 


Chapter 3, “Functions Directory,” contains an alphabetical list of Win- 
dows functions. The documentation for each function gives the syntax, 
states the function’s purpose, lists its input parameters, and describes its 
return value. For some functions, additional information the developer 
needs in order to use those functions is given. 


Chapter 4, “Messages Overview,” categorizes messages in their related 
groups, provides brief descriptions of individual messages, and supplies 
additional information about particular message groups. This additional 
information includes definitions of new terms and descriptions of models 
that are unique to Windows. This chapter is designed to assist the applica- 
tion developer who is new to Windows or who has questions about a par- 
ticular group of Windows messages. 


Chapter 5, “Messages Directory,” contains an alphabetical list of Windows 
messages. The documentation for each message states the message’s pur- 
pose, lists its input parameters, and describes its return value (if one 
exists). For some messages, additional information the developer needs in 
order to use those messages is given. 


Chapter 6, “Data Types and Structures,” contains a table of data types 
and an alphabetical list of structures found in Windows. 


Chapter 7, “File Formats,” describes of the formats of three types of files: 
font files, executable files, and the Windows initialization file. Each 
description gives the general file structure and information about specific 
parts of the file. 
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Appendix A, “Binary and Ternary Raster-Operation Codes and Defini- 
tions,” describes the raster operations used for line output and those used 
for bitmap output. Appendix B, “Binary-Resource File Format for Icons 
and Cursors,” describes the binary format of a Windows resource file. 
Appendix ©, “Printer Escapes,” lists the printer escapes that are available 


in Windows. 


1.10.1 Notational Conventions 


The following notational conventions are used throughout this manual: 


Convention 


bold 


italics 


(Parentheses) 


[Double brackets] 


Monospace 
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Meaning 


Bold is used for keywords, such as function, data-type, 
structure, and macro names. These names are spelled 
exactly as they should appear in source programs. 
Notice the bold in the following example: 


HDC GetDC(hWnd) 


Here, HDC is bold to indicate that it 1s the return 
value (in this particular case, the return value is a 
handle to a device context). GetDC is bold to indicate 
that it is the name of a function. 


Italics are used to indicate a placeholder that should 
be replaced by an actual argument. In the preceding 
example, hWnd is italic to indicate that it should be 
replaced by an argument. 


Parentheses enclose the parameter or parameters that 
are to be passed to a function. In the preceding exam- 
ple, hWnd is the parameter. 


Double brackets are used to enclose optional argu- 
ments. 


Monospace type is used for program code fragments 
and to illustrate the syntax of data structures. 
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Functions Overview 


2.1 Introduction 


This chapter describes the three groups of related Microsoft Windows 
functions: the window manager interface, graphics device interface, and 
system services interface groups. Each section contains an introduction 
that describes the purpose of the function group, and then lists and 
describes each function in the group. Some of the sections contain addi- 
tional information. 


2.2 Window Manager Interface 
Function Groups 


The window manager interface contains the functions that process mes- 


sages, create, move, or alter a window, or create system output. 


2.2.1 Message Functions 


Message functions read and process Windows messages in an application’s 
queue. Messages represent a variety of input to a Windows application. A 
message is a data structure that contains a message identifier and message 
parameters. The content of the parameters varies with the message type. 
The following list briefly describes each function: 


Function Description 

CallWindowProc Passes message information to the specified 
function. 

DispatchMessage Passes a message to a window function of 
the specified window. 

GetMessage Retrieves a message from the specified 
range. 

GetMessagePos Returns the position of the mouse at the 
time the last message was retrieved. 

GetMessageTime Returns the time at which the last message 
was retrieved. 

PeekMessage Checks the application queue and places the 
message appropriately. 

PostAppMessage Posts a message to the application. 
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PostMessage Places a message in the application queue. 

PostQuitMessage Posts a WM_ QUIT message to the appli- 
cation. 

Reply Message Replies to a message. 

SendMessage Sends a message to a window or windows. “* 

SetMessageQueue Creates a new message queue of a different 
size. 

TranslateAccelerator Processes keyboard accelerators for menu 
commands. 

TranslateMessage Translates virtual keystroke messages into 
character messages. 

WaitMessage Yields control to other applications. 

WinMain Serves as an entry point for execution of 


a Windows application. 


2.2.1.1 Generating and Processing Messages 


Windows generates a message at each input event, such as when the user 
moves the mouse or presses a keyboard key. Windows places these mes- 
sages, as well as timer and paint messages, in an application’s queue. The 
application queues are first-in/first-out queues that belong to individual 
applications. Windows places messages that belong to an application 

in the queue. The application then reads the messages by using the 
GetMessage function and dispatches them to the appropriate window 
function by using the Dispatch Message function. 


Windows sends some messages directly to an application’s window func- 
tion, without placing them in the application queue. Such messages are 

called unqueued messages. In general, an unqueued message is any mes- 

sage that affects the window only. 


For example, the CreateWindow function directs Windows to send a 
WM. CREATE message to the window function of the application and to 
wait until the message has been processed by the window function. Win- 
dows sends this message directly to the function and does not place it in 
the application queue. 


Although most messages are generated by Windows, applications can 


create their own messages and place them in the application queues of tay 
other applications. 
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An application can pull messages from its queue by using the Get- 
Message function. This function searches the application queue for mes- 
sages and, if a message exists, returns the top message in the application 
queue. If the application queue 1s empty, GetMessage waits for a mes- 
sage to be placed in the queue. While waiting, GetMessage relinquishes 
control to Windows, allowing other applications to take control and pro- 
cess their own messages. 


Once a main function has a message from a queue, it can dispatch the mes- 
sage to a window function by using the DispatchMessage function. This 
function directs Windows to call the window function of the window asso- 
ciated with the message, and then pass the content of the message as func- 
tion arguments. The window function can then process the message and 
carry out any requested changes to the window. When the window func- 
tion returns, Windows returns control to the main function. The main 
function can then pull the next message from the queue. 


Windows generates a virtual-key message each time the user presses a 
keyboard key. The virtual-key message contains a virtual-key code that 
defines which key was pressed, but does not define the character value of 
that key. To retrieve the character value, the main function must trans- 
late the virtual-key message by using the TranslateMessage function. 
This function puts another message with an appropriate character value 
in the application queue. The message can then be dispatched to a win- 
dow function. 


The TranslateMessage function can translate virtual-key codes into 
ANSI character values or OEM-specific character values. The style of the 
window associated with the message defines what kind of translation 
occurs. This means TranslateMessage can convert a virtual-key code 
into a single character value or into special-purpose or multiple-character 
values, such as foreign language characters. If TranslateMessage gen- 
erates multiple characters, it places multiple messages in the application 
queue. 


2.2.1.2 Translating Messages 
In general, a main function should use the TranslateMessage function 
to translate every message, not just virtual-key messages. Although 


TranslateMessage has no effect on other types of messages, it guaran- 
tees that any keyboard input is translated correctly. 
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An application can send virtual-key messages directly to an application’s 
window function, if desired, by using the SendMessage function. If 
SendMessage is used, the message must be translated in the window 
function. 


The following program fragment illustrates the typical loop that a main 
function uses to pull messages from the queues and dispatch them to win- 
dow functions: 


int PASCAL WinMain(hInstance, hPrevInstance, lpCmdLine, ShowCmd) 
HANDLE hInstance; 

HANDLE hPreviInstance; 

LPSTR lpCmdLine; 

int ShowCmd; 

{ 


while (GetMessage((LPMSG) &msg, NULL, ©, 0)) 
{ 


TranslateMessage ( (LPMSG) &msq) ; 
DispatchMessage ( (LPMSG) &msq) ; 


exit (msg.wParam) ; 


Applications that use accelerator keys must load an accelerator table 
from the resource file by using the LoadAccelerator function, and then 
translate keyboard messages into accelerator-key messages by using the 
TranslateAccelerator function. The main loop for applications that 
use accelerator keys should have the following form: 


while (GetMessage ((LPMSG) &msg, (HWND)NULL, O, 0O)) 
if (TranslateAccelerator (hWindow, hAccel, ((LPMSG)&msg) == 0) 
{ 
TranslateMessage ( (LPMSG) &msq) ; 
DispatchMessage ( (LPMSG) &msqg) ; 
} 


exit (msg.wParam) ; 


The TranslateAccelerator function must appear before the standard 
TranslateMessage and DispatchMessage functions. Furthermore, 
since TranslateAccelerator automatically dispatches the accelerator 
message to the appropriate window function, the TranslateMessage 
and DispatchMessage functions should not be called if Translate- 
Accelerator returns a nonzero value. 
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2.2.1.3 Examining Messages 


An application can use the PeekMessage function when it checks the 
queues for messages but does not want to pull the message from the queue. 
The function returns a nonzero value if a message is in the queue, and lets 
the application retrieve the message and process it without going through 
the application’s main loop. 


Typically, PeekMessage is used to check periodically for messages when 
the application is carrying out a lengthy operation, such as processing 
input and output. For example, this function can be used to check for 
messages that terminate the operation. 


The SendMessage and PostMessage functions let applications pass 
messages to their windows or to the windows of other applications. 


The SendMessage function directs Windows to send a message directly 
to the given window function, bypassing the application queue. Windows 
does not return control to the calling application until the window func- 
tion that receives the message processes the message. SendMessage is 
typically used to send messages to child windows. 


The PostMessage function directs Windows to post the message by plac- 
ing it in the application queue. Control returns immediately to the calling 
application, and any action to be carried out as a result of the message 
does not occur until the message is read from the queue. 


In most applications, only the main function uses the message functions to 
pull messages from the queues. Any window function can also call the mes- 
sage functions if it has a special need for input, such as when it is tracking 
the mouse or reading keystrokes in advance. Windows places no restric- 
tions on when or where a message function is called. 


Windows communicates with applications through formatted window 
messages. The messages are passed (sent or posted) to an application’s 
window function to let the function process the messages as desired. 
Although an application’s main function may read and dispatch window 
messages, in most cases only the window function processes them. 
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2.2.2 Window-Creation Functions 


Window-creation functions create, destroy, modify, and obtain informa- 
tion about windows. The following list briefly describes each window- 


creation function: 
Function 


Create Window 
DefWindowProc 


Destroy Window 
GetClassLong 


GetClassName 
GetClassWord 


Get WindowLong 
Get Window Word 
RegisterClass 
SetClassLong 


SetClassWord 


Set WindowLong 
Set Window Word 
WndProc 
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Description 
Creates overlapped, pop-up, and child 
windows. 


Provides default processing for messages an 
application does not process. 


Sends a WM_ DESTROY message. 


Retrieves window-class information from a 
WNDCLASS structure. 


Retrieves a window-class hame. 


Retrieves window-class information from a 


WNDCLASS structure. 
Retrieves information about a window. 
Retrieves information about a window. 


Registers a window class. 


Replaces information in a WNDCLASS 
structure. 


Replaces information in a WNDCLASS 


structure. 
Changes a window attribute. 
Changes a window attribute. 


Processes messages sent by Windows or by 
an application. 
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2.2.2.1 Window Classes 


A window class is a set of attributes that defines how a window looks and 
behaves. Before an application can create and use a window, it must define 
and register a window class for that window. An application registers a 
class by passing values for each element of the class to the RegisterClass 
function. Any number of window classes can be registered. Once a class 
has been registered, Windows lets the application create any number of 
windows belonging to that class. The registered class remains available 
until another class with the same name is registered or the application 
terminates. 


Although the complete window class consists of many elements, Windows 
only requires that an application supply a unique class name to distinguish 
the class from all other registered classes, an address to the window pro- 
cedure that will process all messages sent to windows belonging to this 
class, and an instance handle that identifies the application that registered 
the class. The other elements of the window class define default attributes 
for windows of the class, such as the shape of the system cursor and the 
content of the menu for the window. 


2.2.2.2 Elements of a Window Class 

The elements of the window class define the default behavior of the 
windows created from that class. The application that registers the 
window class assigns elements to the class by setting appropriate fields 
ina WNDCLASS data structure and passing the structure to the 
RegisterClass function. 


Table 2.1 shows the window class elements: 
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Table 2.1 


Window Class Elements 


Element 


Purpose 


Class name 


Window procedure address 


Instance handle 
Class cursor 


Class icon 


Class background brush 


Class menu 


Class styles 


Class extra 


Window extra 


Distinguishes the class from other registered 
classes. 


Points to the function that processes all messages 
that are sent to windows in the class, and defines 
the behavior of the window. 


Identifies the application that registered the class. 


Defines the shape of the system cursor when the 
cursor is in a window of the class. 


Defines the shape of the icon Windows displays 
when an overlapped window belonging to the 
class is closed. 


Defines the color and pattern Windows uses to 
fill the client area when the window is opened 
or painted. 


Specifies the default menu used for any window 
in the class that does not explicitly define a menu. 


Defines how to update the window after moving 
or resizing, how to process double-clicks of the 
mouse, how to allocate space for the display 
context, and other aspects of the window. 


Specifies the amount of memory (in bytes) that 
Windows should reserve at the end of the class 
data structure. 


Specifies the amount of memory (in bytes) that 
Windows should reserve at the end of any win- 
dow structure an application creates with this 
class. 


Sections 2.2.2.3 through 2.2.2.10 describe the elements of a window class 
and explain the default values for these elements if no explicit value is 
given when the class is registered. 
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2.2.2.3 Class Name 


Every window class needs a class name. The class name distinguishes one 
class from another and lets an application identify the class to which the 
window being created belongs. An application assigns a class name to the 
class by setting the lpszClassName field of the WNDCLASS structure 


to the address of a null-terminated string that contains the name. 


Windows keeps all registered classes for all applications in the same inter- 
nal pool. To help Windows keep the classes separate, each class name 
must be unique. If two applications register a class with the same name, 
Windows uses the most recently registered class and ignores the other; 
since no two applications can share a window class, this can lead to serious 
problems. 


To avoid class name conflicts, applications should supply class names that 
are unique among all applications. One possibility is to include the name 
of the application in each class name. Windows does not check class 
names, so the application must ensure that its class names are unique. 


2.2.2.4 Window-Function Address 


Every class needs a window-function address. The address defines the 
entry point of the window function that is used to process all messages 
for windows in the class. Windows passes messages to the function when 
it wants the window to carry out tasks, such as painting its client area 
or responding to input from the user. An application assigns a window- 
function address by copying the address to the lpfnWndProc field of 
the WNDCLASS structure. 


For details about the window function, see Section 2.2.2.17. 


2.2.2.5 Instance Handle 


Every window class needs an instance handle to identify the application 
that registered the class. As a multitasking system, Windows lets several 
applications run at the same time, so it needs instance handles to keep 
track of all applications. Windows assigns a unique handle to each copy 
of a running application. 


Windows passes an instance handle to an application when the application 


first begins operation. The application assigns this instance handle to the 
class by copying it to the hInstance field of the WNDCLASS structure. 
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2.2.2.6 Class Cursor 


The class cursor defines the shape of the system cursor when the cursor 1s 
in the client area of a window in the class. Windows automatically sets the 
system cursor to the given shape as soon as the cursor enters the window’s 
client area, and ensures that the cursor keeps that shape while it remains 
in the client area. To assign a cursor shape to a window class, an applica- 
tion typically loads the shape from the application’s resources by using the 
LoadCursor function, and then assigns the returned cursor handle to the 


hCursor field of the WNDCLASS structure. 


Windows does not require a class cursor. If a class cursor is not defined, 
Windows assumes that the window will set the cursor shape each time the 
cursor moves into the window. 


2.2.2.7 Class Icon 


The class icon defines the shape of the icon used when the top-level win- 
dow of the given class is closed. Windows automatically places the icon, 
a 32 X 32-bit bitmap or a 32 X 16-bit bitmap, in the icon area of the 
system display whenever an overlapped window is closed. To assign an 
icon to a window class, an application typically loads the icon from the 
application’s resources by using the LoadIcon function, and then assigns 
the returned icon handle to the hIcon field of the WNDCLASS 
structure. 


Windows does not require a class icon. If a class icon is not defined, Win- 
dows assumes the application will draw the icon whenever the window is 
closed. In this case, Windows sends an appropriate message to the window 
procedure, requesting that the icon be painted. 


2.2.2.8 Class Background Brush 


A class background brush is the brush used to prepare the client area of 

a, window for subsequent drawing by the application. Windows uses the 
brush to fill the client area with a solid color or pattern, thereby removing 
all previous images from that location whether they belonged to the win- 
dow or not. 


To assign a background brush to a class, an application typically creates a 
brush by using the appropriate functions from GDI, and then assigns the 
returned brush handle to the hbrBackground field of the WNDCLASS 


structure. 
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Instead of creating a brush, an application can use a standard system color 
by setting the field to one of the following color values: 


COLOR_ ACTIVECAPTION 
COLOR APPWORKSPACE 
COLOR_ BACKGROUND 
COLOR. CAPTIONTEXT 
COLOR_ INACTIVECAPTION 
COLOR_ MENU 

COLOR _ MENUTEXT 
COLOR_ SCROLLBAR 
COLOR_ WINDOW 
COLOR WINDOWFRAME 
COLOR_ WINDOWTEXT 


To use a standard system color, the application must increase the back- 
ground-color value by one. For example, COLOR BACKGROUND + 1 is 
the system background color. 


2.2.2.9 Class Menu 


A class menu defines the default menu to be used by the windows in the 
class if no explicit menu is given when the windows are created. A menu is 
a list of commands that appears at the top of a window, under the title 
bar, from which a user can select actions for the application to carry out. 
To assign a menu to a class, an application sets the lpszMenuName field 
of the WNDCLASS structure to the address of a null-terminated string 
that contains the resource name of the menu. The menu is assumed to be 
a resource in the given application. Windows automatically loads the 
menu when it is needed. Note that if the menu resource is identified by an 
integer and not by a name, the lpszMenuName field can be set to that 
integer value by applying the MAKEINTRESOURCE macro before 


assigning the value. 


Windows does not require a class menu. If a menu is not given, Windows 
assumes that the windows in the class have no menus. Even if no class 
menu is given, an application can still define a menu for a window when 
it creates the window. 


Windows does not allow menus with child windows. If a menu is given and 
a child window is created using the class, the menu is ignored. 
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2.2.2.10 Class Styles 


The class styles define additional elements of the window class. ‘T'wo or 
more styles can be combined by using the bitwise OR operator. Table 2.2 


lists the class styles: 


Table 2.2 
Window Class Styles 


Style 
CS_ BYTEALIGNCLIENT 
CS_ BYTEALIGNWINDOW 
CS_ CLASSDC 
CS_.DBLCLKS 
CS_HREDRAW 
CS_NOCLOSE 
CS_OEMCHARS 
CS_OWNDC 
CS_SAVEBITS 


CS. VREDRAW 


Description 


Aligns the window’s client area on a byte 
boundary (in the 2 direction). 


Aligns the window on a byte boundary (in the 
z direction). 


Allocates one display context to be shared by all 
windows in the class. 


Sends double-click messages to the window 
function. 


Requests that the entire client area be redrawn if 
a movement or adjustment to the size changes 
the width of the client area. 


Inhibits the close option on the system menu. 


Specifies OEM translation for keyboard 
characters. 


Allocates a unique display context for each win- 
dow in the class. 


Saves the window’s bitmap; the application can 
use the bitmap to re-create the original window. 


Requests that the entire client area be redrawn if 
a movement or adjustment to the size Rn ee 
the height of the chent area. 


To assign a style to a window class, an application assigns the style value 
to the style field of the WNDCLASS structure. Sections 2.2.2.11 
through 2.2.2.13 describe the class styles in more detail. 
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2.2.2.11 Redrawing the Client Area 


When a window 1s moved, Windows automatically copies the contents of 
the client area to the new location. This saves time since a window does 
not have to recalculate and redraw the contents of the client area as part 
of the move. If the window moves and changes size, Windows copies only 
as much of the previous client area as 1s needed to fill the new location. If 
the window increases in size, Windows copies the entire client area and 
sends a WM. PAINT message to the window to fill in the newly exposed 
areas. When a window is moved, Windows assumes the contents of the 
client area remain valid and can be copied without modification to the 
new location. 


For some windows, however, the contents of the client area are not valid 
after a move, especially if the move includes a change in size. For example, 
a clock application whose window must always contain the complete image 
of the clock has to redraw the window anytime the window changes size, 
and has to update the time after the move. To prevent the windows from 
copying the previous contents of the client area, a window should specify 


the CS_VREDRAW and CS. HREDRAW styles in the window class. 


2.2.2.12 Double-click Mouse Messages 


A double-click mouse message is an input message that a window receives 
when the user clicks a mouse button twice within a time defined by the 
system. Many applications use double-click messages to let the user specify 
special actions or commands. 


Windows generates double-click messages by monitoring mouse messages. 
Windows does not generate double-click messages for a window unless the 


CS. DBLCLKS style is given for the window class. 


2.2.2.13 Class and Private Display Contexts 


A display context is a special set of values that applications use for draw- 
ing in the client area of their windows. Windows requires a display context 
for each window on the system display, but allows some flexibility in how 
that display context is stored and treated by the system. 


If no explicit display context is given, Windows assumes that each window 
in the given class will use a common display context, one retrieved from a 

pool of contexts maintained by Windows. In such cases, each window must 
retrieve and initialize the display context before painting, and then free it 

after painting. 


33 


Microsoft Windows Programmer’s Reference 


In order not to retrieve a display context each time it wants to paint in a 
window, an application can specify the CO9_OWNDC style for the window 
class. This class style directs Windows to create a private display context, 
that is, to allocate a unique display context for each window in the class. 
The application need only retrieve the context once, and then use it for all 
- subsequent painting. Although the CS_OWNDC style is convenient, it 
must be used carefully because each display context occupies approxi- 
mately 800 bytes of memory. 


By specifying the CS. CLASSDC style, an application can have some of 
the convenience of a private display context without allocating a separate 
display context for each window. The CS_CLASSDC style directs Win- 
dows to create a single class display context, that is, one display context 
to be shared by all windows in the class. An application need only retrieve 
the display context for a window, then as long as no other window in the 
class retrieves that display context, the window can continue to use the 
context. 


2.2.2.14 Shared Window Classes 


Applications must not share registered classes with other applications. 

Some information in a window class, such as the address of the window 
function, is specific to a given application and cannot be used by other 

applications. 


Although applications must not share registered classes, different instances 
of the same application can share a registered class. Once a window class 
has been registered by an application, it is available to all subsequent 
instances of that application. This means that new instances of an applica- 
tion do not need to, and should not, register window classes that have been 
registered by previous instances. 


2.2.2.15 Predefined Window Classes 


Windows provides several predefined window classes. These classes define 
special control windows that carry out common input tasks that let the 
user input text, direct scrolling, and select names from a list of names. The 
predefined window classes are available to all applications and can be used 
any number of times to create any number of these control windows. 
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2.2.2.16 Registering a Window Class 


When Windows registers a window class, it copies the attributes into its 
own memory area. Windows uses the internally stored attributes when an 
application later refers to the window class by name; it is not necessary for 
the application that originally registered the class to keep the structure 
available. 


2.2.2.17 Window Function 


A window function processes all messages sent to a window in a given 
class. Windows sends messages to a window function when it receives 
input from the user that is intended for the given window, or when it 
needs information or the procedure to carry out some action on its win- 
dow, such as painting in the client area. 


A window function must examine each message, decide whether it needs 
to process the message, and then either process it or pass it to the 
DefWindowProc function, the Windows default message processor. 


A window function receives input messages from the keyboard, mouse, and 
timer. It receives requests for information, such as a request for the win- 
dow title. It receives reports of changes made to the system by other win- 
dows, such as a change to the win.znz file. It receives messages that give it 
an opportunity to modify the standard system response to certain actions, 
such as an opportunity to adjust a menu before it is displayed. It receives 
requests to carry out some action on its window or client area, such as a 
request to update the client area. And a window function receives informa- 
tion about its status in relation to other windows, such as losing access to 
the keyboard or becoming the active window. 


Most of the messages a window function receives are from Windows, but it 
can also recelve messages from other windows, such as from windows it 
owns. These messages can be requests for information or notification that 
a given event has occurred within another window. 


A window function continues to receive messages from the system and pos- 
sibly other windows in the system until it, the window function of a parent 
window, or the system destroys the window. Even in the process of being 
destroyed, the window function receives additional messages that give it 
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the opportunity to carry out any clean-up tasks before terminating. But 
once the window is destroyed, no more messages are passed to the function 
for that particular window. If there is more than one window of the class, 
however, the window function continues to receive messages for the other 
windows until they, too, are destroyed. 


A window function defines how a given window actually behaves; that is, 
it defines what response the window makes to commands from the user or 
system. The messages the window function receives from the system con- 
tain information that the function knows; for example, the user clicked the 
scroll bar or selected the Open command in the File menu, or double- 
clicked in the client area. The window function must examine these mes- 
sages and determine what action, if any, to take. For example, if the user 
clicks the scroll bar, the window function may scroll the contents of the 
client area. Windows provides detailed information about what happens 
and provides some tools to carry out tasks, such as drawing and scrolling, 
but the window function must carry out the actual task. 


A window function can also choose not to respond to a given message. If it 
does not respond, the function must give the system the opportunity to 
respond by passing the message to the DefWindowProc function. This 
function carries out default actions based on the given message and its 
parameters. Many messages, especially non-client-area messages, must be 
processed, so the DefWindowProc function is required in all window 
functions. 


A window function also receives messages that are really intended to be 
processed by the system. These messages, called non-client-area messages, 
inform the function either that the user has carried out some action in a 
non-client area of the window, such as clicking the title bar, or that some 
information about the window is required by the system to carry out an 
action, such as for moving or adjusting the size of the window. Although 
Windows passes these messages to the window function, the function 
should pass them to the DefWindowProc function and not attempt to 
process them. In any case, the window procedure must not ignore the mes- 
sage or return without passing it to DefWindowProc. 
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2.2.2.18 Window Messages 


A window message is a set of values that Windows sends to a window 
function when it requests some action or informs the window of input. 
Every message consists of four values: a handle that identifies the window, 
a message identifier, a 16-bit message-specific value, and a 32-bit 
message-specific value. These values are passed as individual parameters 
to the window function. The window function then examines the message 
identifier to determine what response to make and how to interpret the 
16- and 32-bit values. 


Windows has a wide variety of messages that it or applications can send to 
a window function. Most messages are sent to a window as a result of a 
given function being executed or as input from the user. 


To send a message to a window procedure, Windows expects the window 
function to have four parameters and use the Pascal calling convention. 
The following illustrates the window procedure syntax: 


long FAR PASCAL WndProc(hWnd, wMsg, wParam, [Param) 
HWND hWnd; 

unsigned wMsq; 

WORD wParam; 

DWORD [Param; 


The hWnd parameter identifies the window receiving the message; the 
wMsg parameter is the message identifier; the wParam parameter is 16 bits 
of additional message-specific information; and lParam is 32 bits of addi- 
tional information. The window procedure must return a 32-bit value that 
indicates the result of message processing. The possible return values 
depend on the actual message sent. 


Windows expects to make an intersegment call to the window function, 
so the function must be declared with the FAR attribute. The window- 
function name must be exported by including it in an EXPORTS state- 
ment in the application’s module-definition file. 
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2.2.2.19 Default Window Function 


The DefWindowProc function is the default message processor for win- 
dow functions that do not or cannot process some of the messages sent to 
them. For most window functions, the DefWindowProc function carries 
out most, if not all, processing of non-client-area messages, those messages 
that signify actions to be carried out on parts of the window other than 
the client area. Table 2.3 lists the messages DefWindowProc processes 


and the default actions for each: 


Table 2.3 


Default Actions for Messages 


Message 


WML ACTIVATE 
WM_ CANCELMODE 


WM_ CLOSE 

WM_ CTLCOLOR 

WM_ ERASEBKGND 
WM_ GETTEXT 

WM_ GETTEXTLENGTH 
WML HITTEST 

WM_- MOVECONVERTWINDOW 
WM_ NCACTIVATE 
WML_ NCCALCSIZE 

WM_ NCCREATE 

WM_ NCDESTROY 


WM_ NCLBUTTONDBLCLK 
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Sets or kills the input focus. 


Terminates internal processing of standard 
scroll bar input and releases mouse capture. 


Calls the Destroy Window function. 


Sets the background and text color and 
returns a handle to the brush used to fill the 
control background. 


Fills the client area with the color and pat- 
tern specified by the class brush, if any. 


Copies the window title into a specified 
buffer. 


Returns the length (in characters) of the 
window title. 


Determines what part of the window the 
mouse is In. 


Moves the key-conversion window to the 
specified location. 


Activates or deactivates the window and 
draws the icon or title bar to show the new 
state. 


Computes the size of the client area. 


Initializes standard scroll bars, if any, and 
sets the default title for the window. 


Frees any space internally allocated for the 
window title. 


Tests the given point to determine the 
location of the mouse and, if necessary, 
generates additional messages. 


Table 2.3 (continued) 
Message 
WM_ NCLBUTTONDOWN 


WM_ NCLBUTTONUP 
WM_ NCMOUSEMOVE 


-WM_NOPAINT 
WM_PAINT 

WM_ QUERYENDSESSION 
WM_ QUERYOPEN 
WM_SETREDRAW 


WM. SETTEXT 
WM_SHOWWINDOW 
WM_ SYSCHAR 


WM_ SYSCOMMAND 
WM_SYSKEYDOWN 


2.2.2.20 Window Styles 


Functions Overview 


Default Action 


Determines whether the left mouse button was 
pressed while the mouse was in the non- 
client area of a window. 


Tests the given point to determine the loca- 
tion of the mouse and, if necessary, generates 
additional messages. 


Tests the given point to determine the loca- 
tion of the mouse and, if necessary, generates 
additional messages. 


Paints the non-client parts of the window. 
Validates the current update region. 
Returns TRUE. 

Returns TRUE. 


Forces an immediate update of information 
about the clipping area of the complete 
window. 


Sets and displays the window title. 

Opens or closes a pop-up window if it is hid- 
den by a zoomed window; has no effect on 
other windows. 


Generates a WM_SYSCOMMAND message 


for menu input. 
Carries out the requested system command. 
Examines the given key and generates a 


WM_SYSCOMMAND message if the key 
is either a TAB or ENTER key. 


Windows provides several different window styles that can be com- 
bined to form different kinds of windows. The styles are used in the 
Create Window function when the window is created. 


Overlapped Windows 


An overlapped window is always a top-level window. In other words, an 
overlapped window never has a parent window and never belongs to any 
other window. It has a client area, a border, and a title bar. It can also 
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have a system menu, minimize/maximize boxes, scroll bars, and a menu, 
if these items are specified when the window is created. For windows used 
as a main interface, the system menu and minimize/maximize boxes are 
strongly recommended. 


Every overlapped window has a corresponding icon that Windows displays 
in the icon area of the system display when the window is closed. Windows 
minimizes an overlapped window by removing it from the display and 
placing the window’s icon in the icon area. A closed window is not de- 
stroyed. It can be opened again by restoring the icon. Windows opens the 
window by removing the icon and displaying the open window as the top- 
level window. An application makes a window iconic to save screen space 
when several windows are open at the same time. 


You create an overlapped window by using the WS. OVERLAPPED style 
with the Create Window function. 


Pop-up Windows 


A pop-up window can overlap any other window on the system display, — 
including overlapped windows. It is the window style most often used to 
temporarily display important information about the current command or 
to request immediate input from the user. It is also the style used for the 
main user interface on other systems that support windows. 


A pop-up window can be displayed anywhere on the system display. Win- 
dows always positions a pop-up window relative to the upper-left corner 
of the screen, and always specifies a pop-up window’s location in screen 
coordinates. 


A pop-up window has a client area, but it does not have a border or title 
bar or any other feature unless these are explicitly requested. As well 

as a border or title bar, an application can request a system menu, 
minimize/maximize boxes, scroll bars, or a menu for a pop-up window. 
To distinguish the pop-up window from overlapped windows, many appli- 
cations request a dialog frame for a pop-up window instead of a border. 


The window class of a pop-up window does not have to be the same as the 
window class of its parent window. A parent window is a window that has 
no predecessors. The window classes of most pop-up windows are very 

different from the classes of their parent windows. A pop-up window Is an 
independent window that receives its own input and other messages. This 
means that input and other messages intended for a pop-up window go daset 
directly to it, even if it has a parent window. 


40 


Functions Overview 


If a pop-up window has a parent window, actions that affect the parent 
window can also affect the pop-up window. The following is a list of 
actions affecting parent windows that can then affect pop-up windows: 


Parent Window Pop-up Window 

Opened for icon Displayed after the parent window is 
displayed. 

Iconic | Hidden prior to the parent window being 
displayed. 

Destroyed Destroyed prior to the parent window being 
destroyed. 


You create a pop-up window by using the WS_ POPUP window style with 
the Create Window function. A pop-up window can be opened and closed 
by using the Show Window function. 


Child Windows 


A child window is the window style used for windows that are confined to 
the client area of a parent window. Child windows are typically used to 
divide the client area of a parent window into different functional areas. 
For example, the MS-DOS Executive window uses separate child windows 
for the disk-drive icons, the current directory name, and the current direc- 
tory listing. 


You create a child window by using the WS_ CHILD window style with the 
Create Window function. A child window can be opened and closed by 
using the Show Window function. 


Every child window must have a parent window. The parent window can 
be an overlapped window, a pop-up window, or even another child win- 
dow. The parent window relinquishes a portion of its client area to the 
child window, and the child window receives all input from this area. The 
window class of the child windows in the parent window do not have to be 
the same. This means an application can fill a parent window with child 
windows that look different and carry out different tasks. 


A child window has a client area, but it does not have any other feature 

unless these are explicitly requested. An application can request a border, 
title bar, minimize/maximize boxes, and scroll bars for a child window. In 
most cases, the application designs its own features for the child window. 
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Although not required, every child window should have a unique integer 
identifier. The identifier, given in the menu parameter of the Create- 
Window function in place of a menu, helps identify the child window 
when its parent windows has many other child windows. The child window 
should use this identifier in any messages it sends to the parent window. 
This is the way a parent window with several child windows can identify 
which child window is sending the message. 


Windows always positions the child window relative to the upper-left 
corner of the parent window’s client area. The coordinates are always 
client coordinates (for information about mapping, see Section 2.3.4). If 
all or part of a child window is moved outside the visible portion of the 
parent window’s client area, the child window is clipped; that is, the por- 
tion outside the parent window’s client area is not displayed. 


A child window is an independent window that receives its own input and 
other messages. Input intended for a child window goes directly to the 
child window and is not passed through the parent window. The only 
exception is if input to the child window has been disabled by the 
EnableWindow function. In this case, Windows passes any input that 
would have gone to the child window to the parent window instead. This 
gives the parent window an opportunity to examine the input and enable 
the child window, if necessary. 


Actions that affect the parent window can also affect the child window. 
The following is a list of actions affecting parent windows that can then 
affect. child windows: 


Parent Window Child Window 
Shown | | Opened after the parent window. 
Hidden Closed prior to the parent window being 


closed. A child window can be visible only 
when the parent window is visible. 


Destroyed Destroyed prior to the parent window being 
destroyed. 
Moved | Moved with the parent window’s client area. 


The child window is responsible for painting 
after the move. 


Increased in size or zoomed Paints any portions of the parent window 
: that have been exposed as a result of the 
increased size of the client area. 
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Windows does not automatically clip a child window from the parent 
window’s client area. This means the parent window will draw over the 
child window if it carries out any drawing in the same location as the child 
window. Windows does clip the child window from the parent window’s 
chent area if the parent window has a WS_ CLIPCHILDREN style. If the 


child window is clipped, the parent window cannot draw over it. 


A child window can overlap other child windows in the same client area. 
Two child windows of the same parent window may draw in each other’s 
client area unless one child window has a WS_ CLIPSIBLINGS style. 
Sibling windows are child windows that share the same parent window. If 
the application specifies this style for a child window, any portion of that 
child’s sibling window that les within this window will be clipped. 


2.2.2.21 Title Bar 


The title bar, a rectangle at the top of the window, provides space for the 
window title or name. An application defines the window title when it 
creates the window. It can also change this name anytime by using the 
Set Window Text function. If a window has a title bar, Windows lets the 
user use the mouse to move the window. 


Windows gives overlapped windows title bars by default. For pop-up and 
child windows, the WS_ CAPTION window style must be specified when 
the window is created. 


2.2.2.22 System Menu 


The system menu, identified by an icon at the left end of the title bar, is a 
pop-up menu that contains the system commands. The system commands 
are commands selected by the user to direct Windows to carry out actions 
on the window, such as moving and closing it. 


If a system menu or close box is desired for a window, the WS..SYSMENU 
and WS_ CAPTION window styles must be specified when the window is 
created. 


2.2.2.23 Scroll Bars 


The horizontal and vertical scroll bars, bars on the right and lower sides of 
a window, let a user scroll the contents of the client area. Windows sends 
scroll requests to a window as WM_ HSCROLL and WM_ VSCROLL mes- 
sages. If the window permits scrolling, the window function must process 
these messages. 
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A window can have one or both scroll bars. If a window has a scroll bar, 
the WS_ HSCROLL or WS_ VSCROLL window style must be specified 


when the window is created. 


2.2.2.24 Window State 


The window state can be opened or iconic, hidden or visible, and 
enabled or disabled. The initial state of a window can be set by using 


the WS_ ICONIC, WS_ VISIBLE, and WS_ DISABLE window styles. 


Windows creates windows that are initially enabled for input, that is, win- 
dows that can start receiving input messages immediately. In some cases, 
an application may need to disable input to a new window. It can disable 
input by specifying the WS_ DISABLE window style. 


A new window is not displayed until an application opens it by using the 
Show Window function or specifies the WS_ VISIBLE window style when 
it creates the window. For overlapped windows, the WS. ICONIC window 
style creates a window that is iconic initially. 


2.2.2.25 Menu 


A menu is a list of command names that appears at the top of a window 
and below the title bar, if one exists. Windows lets users select commands 
from the menu and sends a corresponding message to the window function 
to indicate which command was selected. Any window, except a child win- 
dow, can have a menu. If no menu is explicitly given when the window is 
ee the window receives the default menu defined by the window 
class. 


2.2.2.26 Life Cycle of a Window 


Because the purpose of any window is to let the user enter data or to let 
the application display information, a window starts its life cycle when the 
application has a need for input or output. A window continues its life 
cycle until there is no longer a need for it, or the application is terminated. 
Some windows, such as the window used for the application’s main user 
interface, last the life of the application. Other windows, such as a pop-up 
window used as a dialog box, may last only a few seconds. 
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The first step in a window’s life cycle is creation. Given a registered win- 
dow class with a corresponding window function, the application uses the 
CreateWindow function to create the window. This function directs 
Windows to prepare internal data structures for the window and to return 
a unique integer value, called a window handle, that the application can 
use to identify the window in subsequent function calls. 


The first message a new window receives is WM. GETMINMAXINFO. The 
second message that the new window receives is the non-client-area crea- 
tion message, WM_ NCCREATE. The Create Window function sends 
this message to the window procedure to inform it that the non-client area 
of the window is being created. Most window procedures pass this message 
to the DefWindowProc function, but a window that has a custom non- 
client area may use it to prepare the data used to draw the custom area. 


The first message most windows process is WM_ CREATE, the window- 
creation message. Again, the Create Window function sends this message 
to inform the window function that it can now perform any initialization, 
such as allocating memory and preparing data files. The wParam parame- 
ter 1s not used, but the /Param parameter contains a long pointer to a 
CREATESTRUCT data structure, whose fields correspond to the 
parameters passed to Create Window. 


Both the WM_ CREATE and WM_ NCCREATE messages are sent directly 
to the window function, bypassing the application queue. This means an 
application will create a window and process the WM_ CREATE message 
before it enters the main program loop. 


After a window has been created, it must be opened (displayed) before it 
can be used. An application can open the window in one of two ways: it 
can specify the WS_ VISIBLE window style in the CreateWindow func- 
tion to open the window immediately after creation, or it can wait until 
later and call the Show Window function to open the window. 


When the window is no longer needed or the application is terminated, the 
window must be destroyed. This is done by using the Destroy Window 
function. Destroy Window removes the window from the system display 
and invalidates the window handle. It also sends WM_ DESTROY and 
WM NCDESTROY messages to the window function. 


The WM_ DESTROY message is usually the last message a window func- 
tion processes. This occurs when the Destroy Window function is called 
or when a WM_ CLOSE message is processed by the DefWindowProc 
function. When a window function receives a WM... DESTROY message, 
it should free any allocated memory and close any open data files. 
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The last message a window function receives is WM_ NCDESTROY. Most 
window functions pass this message on to the DefWindowProc function, 
but a window that has a custom non-client area may free space or data 
that has been allocated for drawing in the non-client area. 


The window used as the application’s main user interface should always be 
the last window destroyed and should always cause the application to ter- 
minate. When this window receives a WM_ DESTROY message, it should 
call the PostQuitMessage function. This function copies a WM_ QUIT 
message to the application’s message queue as a signal for the application 
to terminate when the message is read from the queue. 


2.2.2.27 Internal Data Structures 


Windows maintains internal data structures for each window class and 
window. These structures are not directly accessible to applications but 
can be examined and modified by using the following functions: 


GetClassLong 
GetClassName 
GetClassWord 
Get WindowLong 
Get Window Word 
SetClassLong 
SetClassWord 
Set WindowLong 
Set Window Word 


Section 2.2.2.28 describes some ways in which a window class or window 
_ can be modified. 


2.2.2.28 Window Subclassing 


A subclass is a window or set of windows that belong to the same win- 
dow class, and whose messages are intercepted and processed by another 
window function (or functions) before being passed to the class window 
function. 


To create the subclass, the Set WindowLong function 1s used to change 
the window function associated with a particular window, causing Win- 
dows to call the new window function instead of the previous one. Any 
messages not processed by the new window function must be passed 

to the previous window function by calling the CallWindowProc func- 
tion. This allows Windows to create a chain of window functions. The 
address of the previous window function can be retrieved by using the 
Get WindowLong function before using Set WindowLong. 
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2.2.3 Display and Movement Functions 


Display and movement functions show, hide, move, and obtain informa- 
tion about the number and position of windows on the screen. The follow- 
ing list briefly describes each display and movement function: 


Function 


CloseWindow 
GetChlientRect 
Get WindowRect 


Get Window Text 
Get Window TextLength 


IsIconic 

Is Window Visible 
IsZoomed 

Move Window 


Openlcon 
Set WindowPos 


Set Window Text 
ShowOwnedPopups 
Show Window 


Description 
Hides the specified window or makes it 
iconic. 


Copies the coordinates of a window’s 
client area. 


Copies the dimensions of an entire ~ 
window. 


Copies a window caption into a buffer. 


Returns the length (in characters) of 
the given window’s caption or text. 


Specifies whether a window is open or 
Iconic. 

Determines whether the given window 
is visible. 


Determines whether a window is 
maximized. 


Changes the size and position of a 
window. 


Opens the specified window. 


Changes the size, position, and ordering 
of child or pop-up windows. 


Sets the window caption or text. 


Shows or hides all pop-up windows. 


Displays or removes the given window. 
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2.2.4 Input Functions 


Input functions disable input from system devices, take control of the sys- 
tem devices, or define special actions that Windows takes when an applica- 
tion receives input from a system device. (The system devices are the 
mouse, the keyboard, and the timer.) The following list briefly describes 


each input function: 
Function 


EnableWindow 


GetActiveWindow 
GetCapture 


GetFocus 
Get TickCount 


KillTimer 


ReleaseCapture 


SetActiveWindow 
SetCapture 


SetFocus 
SetSysModalWindow 


Set Timer 
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Description 

Enables and disables mouse and keyboard 
input throughout the application. 
Returns a handle to the active window. 


Returns a handle to the window with the 
mouse capture. 


Retrieves the handle of the window that 
currently owns the input focus. 


Returns the number of timer ticks recorded 
since the system was booted. 


Kulls the specified timer event. 


Releases mouse input and restores normal 
Input processing. 


Makes a window the active window. 


Causes mouse input to be sent to a specified 
window. 


Assigns the input focus to a specified 
window. 


Makes the specified window a system modal 
window. 


Creates a system-timer event. 


Functions Overview 


2.2.5 Hardware Functions 


Hardware functions alter the state of input devices and obtain state infor- 
mation. Windows uses the mouse and the keyboard as input devices. The 
following list briefly describes each hardware function: 


Function 


EnableHardwarelInput 
GetAsyncKeyState 
GetInputState 
GetKeyboardState 
SetKey boardState 


GetKeyState 


Description 
Enables or disables mouse and keyboard 
input throughout the application. 


Returns interrupt-level information about 
the key state. 


Returns TRUE if there is mouse or keyboard 
input. 


Copies an array that contains the state of 
keyboard keys. 


Sets the state of keyboard keys by altering 
values in an array. 


Retrieves the state of a virtual key. 


2.2.6 Painting Functions 


Painting functions prepare a window for painting and carry out some use- 
ful general-purpose graphics operations. Although all the paint functions 

are specifically intended for the system display, some can be used for other 
output devices. The following list briefly describes each painting function: 


Function 


BeginPaint 
Drawlcon 
DrawText 
EndPaint 
ExcludeUpdateRgn 


FillRect 


FrameRect 


Description 


Prepares a window for painting. 
Draws an icon. 

Draws characters of a specified string. 
Marks the end of window repainting. 


Prevents drawing within invalid areas of a 
window. 


Fills a given rectangle by using the specified 
brush. 


Draws a border for the given rectangle. 


49 


Microsoft Windows Programmer’s Reference 


GetDC Retrieves the display context for the client 
area. 

GetUpdateRect Copies the dimensions of a window region’s 
bounding rectangle. 

Get UpdateRgn Copies a window’s update region. 

GetWindowDC Retrieves the display context for an entire 
window. 

GrayString Writes the characters of a string using gray 
text. 

InvalidateRect Marks a rectangle for repainting. 

InvalidateRgn Marks a region for repainting. 

InvertRect Inverts the display bits of the specified 
rectangle. 

ReleaseDC Releases a display context. 

UpdateWindow Notifies the application when parts of a 
window need redrawing. 

ValidateRect Releases the specified rectangle from 
repainting. 

ValidateRgn Releases the specified region from re- 


painting. 


2.2.6.1 Painting on the System Display 


The system display is the principal display device for all applications run- 
ning with Windows. Ail applications are free to display some form of out- 
put on the system display, but since many applications can run at one 
time, applications are not entitled to the entire system display. The com- 
plete system display must be shared. Windows shares the system display 
by carefully managing the access that applications have to it. Windows 
ensures that applications have space to display output but do not draw 


in the space reserved for other applications. 


Windows manages the system display by using the display context type. 
The display context is a special device context that treats each window as 
a separate display surface. An application that retrieves a display context 
for a specific window has complete control of the system display within 
that window, but cannot access or paint over any part of the display out- 
side the window. With a display context, an application can use GDI 
painting functions, as well as the output functions described in this sec- 
tion, to draw in the given window. 
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2.2.6.2 Display Context Types 


There are four types of display context: common, class, private, and win- 
dow. The common, class, and private display contexts permit drawing in 
the client area of a given window. The window display context permits 
drawing anywhere in the window. When a window is created, Windows 
assigns a common, class, or private display context to it, based on the 
type of display context specified in that window’s class style. 


2.2.6.3 Common Display Context 


A common display context is the default context for all windows. Windows 
assigns a common display context to the window if a display-context type 
is not explicitly specified in the window’s class style. 


A common display context permits drawing in a window’s client area, but 
it is not immediately available for use by a window. A common display 
context must be retrieved from a cache of display contexts before a 
window can carry out any drawing in its client area. The GetDC or 
BeginPaint function retrieves the display context and returns a handle 
to the context. The handle can be used with GDI functions to draw in the 
client area of the given window. After drawing is complete, the context 
must be returned to the cache by using the ReleaseDC or EndPaint 
function. After the context is released, drawing cannot occur until another 
display context is retrieved. 


When a common display context is retrieved, Windows gives it default 
selections for pen, brush, font, clipping area, and other attributes. These 
attributes define the tools currently available to carry out the actual draw- 
ing. Table 2.4 lists the default selections for a common display context: 
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Table 2.4 


Defaults for a Display Context 


Attribute 


Background color 
Background mode 
Bitmap 

Brush 

Brush origin 
Clipping region 


Current pen position 
Device origin 
Drawing mode 

Font 

Intercharacter spacing 
Mapping mode 

Pen 

Polygon-filling mode 
Relative-absolute flag 
Stretching mode 
Text color 

Viewport extent 
Viewport origin 
Window extents 
Window origin 


Default 


White 

OPAQUE 

No default. 

WHITE _ BRUSH 

(0,0) 

Entire client area with the 
update region clipped as 
appropriate. Child and pop-up 
windows in the client area may 
also be clipped. 


(0,0) 

Upper-left corner of client area. 
R2__ COPYPEN 
SYSTEM_ FONT 

0 

MM. TEXT 
BLACK_ PEN 
ALTERNATE 
ABSOLUTE 
BLACKONWHITE 
Black 

(1,1) 

(0,0) 

(1,1) 


(0,0) 


An application can modify the attributes of the display context by using 
the selection functions and display-context attribute functions. For exam- 
ple, applications typically change the selected pen, brush, and font. 


When a common display context is released, the current selections, such as 
mapping mode and clipping area, are lost. Windows does not preserve the 
previous selections of a common display context since common display 
contexts are shared and Windows has no way to guarantee that the next 
window to use a given common display context will be the last window to 
use that context. Applications that modify the attributes of a common 
display context must do so each time another context is retrieved. 
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2.2.6.4 Class Display Context 


A window has a, class display context if the window class specifies the 
CS_CLASSDC style. A class display context is shared by all windows in 
a given class. A class display context is not part of the display context 
cache. Instead, Windows specifically allocates a class context for sole use 
by the window class. 


A class display context must be retrieved before it can be used, but it does 
not have to be released after use. As long as only one window from the 
class uses the context, the class display context can be kept and reused. If 
another window in the class needs to use the context, that window must 
retrieve it before any drawing occurs. Retrieving the context sets the 
correct origin and clipping for the new window and ensures that the con- 
text will be applied to the correct window. A handle to the class display 
context can be retrieved by using the GetDC or BeginPaint function. 
The ReleaseDC and EndPaint functions have no effect on the class 
display context. ) 


A class display context is given the same default selections as a common 
display context when the first window of the class is created (see Table 
2.4). These selections can be modified at any time. Windows preserves all 
new selections made for the class display context, except for the clipping 
region and device origin, which are adjusted for the current window when 
the context is retrieved. Otherwise, all other attributes remain unchanged. 
This means a change made by one window applies to all windows that sub- 
sequently use the context. 


Note 


Changing the mapping mode of a class display context may have an 
undesirable effect on how a window’s background is erased. For more 
information, see Section 2.2.6.11 and Section 2.3.4. 


2.2.6.5 Private Display Context 


A window has a private display context if the window class specifies the 
CS_OWNDC style. A private display context is used exclusively by a 
given window. A private display context is not part of the display context 
cache. Instead, Windows specifically allocates the context for sole use by 
the window. 
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A private display context needs to be retrieved only once. Thereafter, it 
can be kept and used any number of times by the window. Windows auto- 
matically updates the context to reflect changes to the window, such as 
moving or sizing. A handle to a private display context can be retrieved 
by using the GetDC or BeginPaint function. The ReleaseDC and 
EndPaint functions have no effect on the private display context. 


A private display context is given the same default selections as a common 
display context when the window is created (see Table 2.4). These selec- 
tions can be modified at any time. Windows preserves any new selections 
made for the context. New selections, such as clipping region and brush, 
remain selected until the window specifically makes a change. 


Note 


Changing the mapping mode of a private display context may have an 
undesirable effect on how the window’s background 1s erased. For more 
information, see Section 2.2.6.11 and Section 2.3.4. 


2.2.6.6 Window Display Context 


A window display context permits painting anywhere in a window, includ- 
ing the caption bar, menus, and scroll bars. Its origin is the upper-left 
corner of the window, instead of the upper-left corner of the client area. 


The GetWindowDC function retrieves a window display context from 
the same cache as it does common display contexts. Therefore, a window 
that uses a window display context must release it with the ReleaseDC 
function immediately after drawing. 


Windows always sets the current selections of a window display context to 
the same default selections as a common display context and does not 
preserve any change the window may have made to these selections (see 
Table 2.4). Windows does not allow private or class window display con- 
texts, so CS. OWNDC and CS_CLASSDC class styles have no effect on 


the window display context. 


A window display context is intended to be used for special painting 
within a window’s non-client area. Since painting in non-client areas of 
overlapped windows is not recommended, most applications reserve a 
display context for designing custom child windows. For example, an 
application may use the display context to draw a custom border 
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around the window. In such cases, the window usually processes the 

WM_ NCPAINT message instead of passing it on to the DefWindowProc 
function. For applications that do not process WM_ NCPAINT messages 
but still wish to paint in the non-client area, the GetSystemMetrics 
function can be used to retrieve the dimensions of various parts of the 
non-client area, such as the caption bar, menu, and scroll bars. 


2.2.6.7 Display-Context Cache 


Windows maintains a cache of display contexts that it uses for common 
and window display contexts. This cache contains five display contexts, 
which means only five common display contexts can be active at any one 
time. To prevent more than five from being retrieved, a window that uses 


a common or window display context must release that context immedi- 
ately after drawing. 


If a window fails to release a common display context, all five display con- 
texts may eventually be active and unavailable for any other window. In 
such a case, Windows ignores all subsequent requests for a common dis- 
play context. 


The ReleaseDC function releases a display context and returns it to the 
cache. Class and private display contexts are individually allocated for 
each class or window; they do not belong to the cache so they do not need 
to be released after use. 


2.2.6.8 Painting Sequence 


Windows carries out many operations to manage the system display that 
affect the content of the client area. If Windows moves, sizes, or alters the 
appearance of the display, the change may affect a given window. If SO, 
Windows marks the area changed by the operation as ready for updating 
and, at the next opportunity, sends a WM_ PAINT message to the window 
SO that it can update the window in the update region. If a window paints 
in its client area, it must call the BeginPaint function to retrieve a han- 
dle to a display context, and to update the changed area as defined by the 
update region, and finally, must call the EndPaint function to complete 
the operation. 


A window is free to paint in its client area at any time, that is, at times 
other than in response to a WM_ PAINT message. The only requirement 
is that it retrieve a display context for the client area before carrying 
out any operations. 
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2.2.6.9 Update Region 


An update region defines the part of the client area that is marked for 
painting on the next WM_PAINT message. The purpose of the update 
region is to save some applications the time it takes to paint the entire 
contents of the client area. If only the part that needs painting 1s added 

to the update region, only that part is painted. For example, if a word 
changes in the client area of a word-processing application, only the word 
needs to be painted, not the entire line of text. This saves the time it takes 
the application to draw the text, especially if there are many different sizes 
and typefaces. 


The InvalidateRect and InvalidateRgn functions add a given rectangle 
or region to the update region. The rectangle or region must be given in 
client coordinates. The update region itself is defined in client coordinates. 
Windows adds its own rectangles and regions to a window’s update region 
after operations such as moving, sizing, and scrolling the window. 


The ValidateRect and ValidateRgn functions remove a given rectangle 
or region from the update region. These functions are typically used when 
the window has updated a specific part of the display in the update region 
before receiving the WM. PAINT message. 


The GetUpdateRect and GetUpdateRgn functions retrieve the small- 
est rectangle that encloses the entire update region. These functions can 
be used to compute the current size of the update region to determine if 
painting is required. 


2.2.6.10 WM_PAINT Message 


The WM_PAINT message is a request from Windows to a given window 
to update its display. Windows sends a WM_ PAINT message to a window 
whenever it is necessary to repaint a portion of an application’s window. 
When a window receives a WM_ PAINT message, it should retrieve the 
update region by using the BeginPaint function, and it should carry out 
whatever operations are necessary to update that part of the client area. 


The InvalidateRect and InvalidateRgn functions do not actually gen- 
erate WM_ PAINT messages. Instead, Windows accumulates the changes 
made by these functions and its own changes while a window processes 
other messages in its application queue. Postponing the WM_ PAINT mes- 
sage lets a window process all changes at once instead of updating bits and 
pieces in time-consuming, individual steps. 
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A window can require Windows to send a WM_PAINT message by using 
the Update Window function. The UpdateWindow function sends the 
message directly to the window, regardless of the number of other mes- 
sages in the application queue. UpdateWindow i is typically used when a 
window wants to update its client area immediately, such as just after the 
window Is created. 

Once a window receives a WM_ PAINT message, it must call the Begin- 
Paint function to retrieve the display context for the client area and to 
retrieve other information such as the update region and whether the 
background has been erased. 


Windows automatically selects the update region as the clipping region 
of the display context. Since GDI discards (clips) drawing that extends 
outside the clipping region, only drawing that is in the update region 
is actually visible. For more information about the clipping region, see 
Section 2.3.7. 


The BeginPaint function empties the update region to prevent the same 
region from generating subsequent WM. PAINT messages. 


After completing the painting operation, the window must call the 
EndPaint function to release the display context. 


2.2.6.11 Window Background 


The window background is the color or pattern the client area is filled 
with before a window begins painting in the client area. Windows 
automatically paints the background for a window, or gives the window 
the opportunity to do so by sending a WM_ERASEBKGND message to 
the window when the background needs painting. 


The background is important since if not erased, the client area will con- 
tain whatever was originally on the system display before the window was 
moved there. Windows erases the background by filling it with the back- 
ground brush specified by the window’s class. 


Windows applications that use class or private display contexts should be 
careful about erasing the background. Windows assumes the background 
is to be computed by using the MM_ TEXT mapping mode. If the display 
context has any other mapping mode, the area erased may not be within 
the visible part of the client area. 
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2.2.6.12 Non-Client-Area Painting 


Windows sends a WM_NCPAINT message to the window whenever the 
non-client area of the window, such as the title bar, menu bar, and win- 
dow frame, needs painting. Processing this message is not recommended 
since a window that does so must be able to paint all the required parts of 
the non-client area for the window. In other words, a window should pass 
this message on to the DefWindowProc function for default processing 
unless the Windows application is creating a custom non-client area for a 
child window. 


2.2.6.13 Painting Rectangles 


The FillRect, FrameRect, and InvertRect functions provide an easy 
way to carry out painting operations on rectangles in the client area. 


The FillRect function fills a rectangle with the color and pattern of a 
given brush. This function fills all parts of the rectangle, including the 
edges or borders. 


The FrameRect function uses a brush to draw a border around a rect- 
angle. The border width and height 1s one unit. 


The InvertRect function inverts the contents of the given rectangle. On 
monochrome displays, white pixels become black, and vice versa. On color 
displays, the results depend on the method used by the display to generate 
color. In either case, calling InvertRect twice with the same rectangle 
restores the display to its original colors. _ 


(2.2.6.14 Brush Alignment 


Brush alignment is particularly important on the system display where 
scrolling and moving are commonplace. A brush is a pattern of bits with a 
minimum size of 8 X 8 bits. GDI paints with a brush by repeating the pat- 
tern again and again within a given rectangle or region. If the region is 
moved by an arbitrary amount—for example, if the window is scrolled— 
and the brush is used again to filled empty areas around the original area, 
there is no guarantee that the original pattern and the new pattern will 
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be aligned. For example, if the scroll moves the original filled area up one 
pixel, the intersection of the original area and any new painting will be out 
of alignment by one pixel, or bit. Depending on the pattern, this may have 
a undesirable visual effect. 


To ensure that a brush is aligned after a window is moved, the 
UnrealizeObject function must be used to release the current align- 
ment of the selected brush. Once that alignment is released, GDI will 
realign the brush before it is used. GDI always aligns a brush on the 
window origin. 


2.2.6.15 Drawing Icons 


The Drawlcon function draws an icon at a given location in the client 
area. An icon is a bitmap that a window uses as a symbol to represent an 
item or concept, such as an application or a warning. 


An icon can be created by using the IconEdit program, added to an 
application’s resources by using the re compiler, and loaded into memory 
by using the LoadIcon function. Applications can also create an icon or 
modify a previously loaded one at any time. An icon resource is in global 
memory and its handle is the handle to that memory. To create an icon, 
you allocate global memory with the same size as the icon data structure, 
and then fill the structure with appropriate values. An icon contains two 
bitmasks: an AND and an XOR bitmask. Windows draws the icon by first 
combining the bits of the AND bitmask with the display, and then com- 
bining the bits of the XOR bitmask with the result. 


If the given icon resource is not available, the DrawIcon function places a 
black icon at the desired location. When drawing an icon, the text color is 
set to white and the background color is set to black. 


Although an application can draw standard system icons, the standard 
system icons’ resources must not be modified. 
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2.2.6.16 Drawing Formatted Text 


The DrawText function formats and draws text within a given rectangle 
in the client area. This function provides simple text processing that 
most applications, other than word processors, can use to display text. 
DrawText output is similar to the output generated by a terminal, 
except it uses the selected font and can clip the text if it extends outside 


a given rectangle. 


DrawText provides many different formatting styles. Table 2.5 lists the 


styles that are available: 


Table 2.5 


Text Formatting Methods 


Value 


DT_ BOTTOM 
DT_ CENTER 
DT_ EXPANDTABS 


DT_ EXTERNALLEADING 


DT_ LEFT 
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Description 


Bottom-justified (single line only). 
Centered. 


Expands tab characters into 
spaces. Otherwise, tabs are treated 
as single characters. The number 
of spaces depends on the tab stop 
size specified by DT_ TABSTOP. 
If DT. TABSTOP is not given, 
the default is eight spaces. 


Includes the font external leading 
in line height. External leading is 
not included in the height of a line 
of text. (Leading is the space 
between lines of text.) If 

DT_ EXTERNALLEADING is not 
given, there is no spacing between 
lines of text. Depending on the 
selected font, this means that 
characters in different lines may 
touch or overlap. 


Left-justified. Default. 
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Table 2.5 (continued) 


Value 
DT_ NOCLIP 


DT_ RIGHT 


DT_ SINGLELINE 


DT_ TABSTOP 


DT_ TOP 


DT_ VCENTER 
DT. WORDBREAK 


Description 


Draws text without clipping. All text 
will be drawn even if it extends outside 
the specified rectangle. The DrawText 
function is somewhat faster when 


DT_ NOCLIP is used. 
Right-justified. 


Single line only. Carriage returns and 
linefeeds do not break the line. Default 
is multiple-line formatting. 


Sets tab stops. The high-order byte of 
the wFormat parameter is the number 
of characters for each tab. If 

DT_ TABSTOP is not given, the 
default tab size is eight spaces. 


Top-justified (single line only). Default. 
Vertically centered (single line only). 


Sets word breaks. Lines are automa- 
tically broken between words if a word 
would extend past the edge of the 
rectangle specified by the [pRect param- 
eter. Carriage-return /linefeed sequence 
also causes a line break. Word-break 
characters are space, tab, carriage 
return, linefeed, and carriage-return / 
linefeed combinations. Applies to 
multiple-line formatting only. 


The DrawText function uses the selected font, so applications can draw 
formatted text in other than the system font. 


DrawText does not hyphenate, and although it can justify text to the 
left, right, or center, it cannot combine justification styles. In other words, 
it cannot justify both left and right. 


Draw Text recognizes a number of control characters and carries out spe- 
cial actions when it encounters them. Table 2.6 lists the control characters 


and the respective action: 
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Table 2.6 


Draw Text Control Characters 


Character (ANSI value) 


Carriage return(13)* 


Linefeed(10)* 


Space(32) 


Tab(9) 


2.2.6.17 Drawing Gray Text 


Action 


Interpreted as a line-break char- 
acter. The text is immediately 
broken and started on the next 
line down in the rectangle. 


Interpreted as a line-break char- 
acter. The text is immediately 
broken and started on the next 
line down in the rectangle. 


A carriage-return/linefeed char- 
acter combination is interpreted 
as a single line-break character. 


Interpreted as a word-break char- 
acter if the DT_ WORDBREAK 
style is given. If the text is too long 
to fit on the current line in the 
formatting rectangle, the line is 
broken at the closest word-break 
character to the end of the line. 


Expanded into a given 
number of spaces if the 
DT_ EXPANDTABS style is 
given. The number of spaces 
depends on what tab-stop 
value is given with the 


- DT_ TABSTOP style. 


The default is 8. 


The GrayString function is a multiple-purpose function that gives appli- 
cations a way to gray text or carry out other customized operations on 
text or bitmaps before drawing the result in a client area. To gray text, 
the function creates a memory bitmap, draws the string in the bitmap, 
and then grays the string by combining it with a gray brush. The Gray- 
String function finally copies the gray text to the display. An application 
can intercept or modify each step of this process, however, to carry out 
custom effects, such as changing the gray brush to a patterned brush or 
drawing an icon instead of a string. 
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lf GrayString is used to draw gray text only, the font used is always 

the system font. GrayString does not use the selected font of the given 
display context. GrayString sets text color to black. It creates a bitmap, 
and then uses the TextOut function to write a given string to the bit- 
map. It then uses the PatBlt function and a gray brush to gray the text, 
and uses the BitBlit function to copy the bitmap to the client area. 


GrayString assumes that the display context for the client area has 
MM TEXT mapping mode. Other mapping modes cause undesirable 
results. 


GrayString lets an application modify this graying procedure in three 
ways: by defining an additional brush to be combined with the text before 
being displayed, by replacing the call to the TextOut function with a 
call to an application-supplied function, and by disabling the call to the 
PatBlt function. | 


The additional brush is defined as a parameter. This brush is combined 
with the text as the text is being copied to the client area by the BitBIt 
function. The additional brush is intended to be used to give the text a 
desired color, since the bitmap used to draw the text is a monochrome 
bitmap. | 


The application-supplied function is also defined as a parameter. If a non- 

LL value is given for the function, GrayString automatically calls the 
application-supplied function instead of the TextOut function and passes 
it a handle to the display context for the memory bitmap as well as the 
long pointer and count passed to GrayString. The function can carry out 
any operation and interpret the long pointer and count in any way. For 
example, a negative count could be used to indicate that the long pointer 
is to an icon handle that signals the application-supplied function to draw 
the icon and let GrayString gray and display it. No matter what type of 
drawing the function carries out, GrayString assumes it is successful if 
the application-supplied function returns TRUE. 


GrayString suppresses graying if it receives an ncount parameter equal to 

—1 and the application-supplied function returns FALSE. This is a way to 

oes custom patterns with the text without interference from the gray 
rush. 
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2.2.7 Dialog Functions 


Dialog functions create, alter, test, and destroy dialog boxes and controls 
within dialog boxes. A dialog box is a temporary window that Windows 


creates for special-purpose input, and then destroys immediately after use. 
An application typically uses a dialog box to prompt the user for addi- 


tional information about a current command selection. The following list 
briefly describes each dialog function: 


Function 


CheckDlgButton 
CheckRadioButton 


CreateDialog 
CreateDialogIndirect 
DialogBox 

Dialog BoxIndirect 
DigDirList 


DlgDirSelect 

| EndDialog 
GetDligItem 
GetDlgItemInt 


GetDlgItemText 


GetNextDlgGroupItem 


GetNextDlgTablItem 
IsDialogMessage 


IsDigButtonChecked 
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Description 
Places/removes a check, or changes the state 
of the three-state button. 


Checks a specified button and removes 
checks from all others. 


Creates a modeless dialog box. 
Creates a modeless dialog box. . 
Creates a modal dialog box. 
Creates a modal dialog box. 


Fills the list box with names of files match- 
ing a path. 


_ Copies the current selection from a list box 


to a string. 


Frees resources and destroys windows associ- 
ated with a modal dialog box. 


Retrieves the handle of a dialog item from 
the given dialog box. 


Translates the text of an item into an 
integer value. 


Copies an item’s control text into a string. 


Returns the window handle of the next item 
in a& group. 

Returns the window handle of the next or 
previous item. 


Determines whether a message is intended 
for the given dialog box. 


Tests whether a button is checked. 
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MapDialogRect Converts the dialog-box coordinates to 
client coordinates. 

SendDlgItemMessage Sends a message to an item within a dialog 
box. 

SetDlgItemInt Sets the text of an item to a string that 
represents an integer. 

SetDlgItem Text Sets the caption or text of an item toa 
string. 


2.2.7.1 Example: Dialog Box 


A dialog box is a pop-up or child window that contains one or more con- 
trols. The About box command for the MS-DOS Executive is an example 
of a typical dialog box. The MS-DOS Executive displays this dialog box 
whenever the user chooses the About box command. The dialog box con- 
tains text, an icon, and a push-button control. 


2.2.7.2 Using Dialog Boxes 


For convenience and to keep from introducing device-dependent and 
country-dependent values into the application code, applications use dia- 
log boxes instead of creating their own windows. This device-independence 
is maintained by using logical coordinates in the dialog-box template. 
Dialog boxes are convenient to use because all aspects of the dialog box, 
except how to carry out its tasks, are predefined. Dialog boxes supply a 
window class and procedure, and create the window for the dialog box 
automatically. The application supplies a dialog function to carry out 
tasks and a dialog-box template that describes the dialog style and 
content. 


2.2.7.3 Creating a Dialog Box 


A dialog box is created by using either the CreateDialog or DialogBox 
function. These functions load a dialog-box template from the appli- 
cation’s executable file, and then create a pop-up or child window that 
matches the template’s specifications. The dialog box belongs to the 
predefined dialog-box class unless another class is explicitly defined. The 
DialogBox function creates a modal dialog box; the CreateDialog func- 
tion creates a modeless dialog box. 


Use the WS_ VISIBLE style for the dialog-box template if you want the 
dialog box to appear upon creation. 
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2.2.7.4 Dialog-Box Template 


The dialog-box template is a description of the dialog box: its height and 
width, the controls it contains, its style, the type of border it uses, and 
so on. A template is an application’s resource and must be added to the 
application’s executable file by using the re resource compiler. 


Dialog boxes can be easily modified and are system-independent, enabling 
an application developer to change the template without changing the 
source code. The dimensions in the template are given in character widths 
and heights. 


The CreateDialog and DialogBox functions load the resource into 
memory when they create the dialog box, and then use the information 
in the dialog template to create the dialog box, position it, and create 
and position the controls for the dialog box. 


The compiler takes a text description of the template and converts it to 
the required binary form. This binary form is added to the application’s 
executable file. For information on the binary format of a dialog-box 
template, see Chapter 7, “File Formats.” 


2.2.7.5 Modeless Dialog Box 


A modeless dialog box allows the user to supply information to the dialog 
box and return to the previous task without canceling or removing the dia- 
log box. Modeless dialog boxes are typically used as a way to let the user 
continually supply information about the current task without having to 
select a command from a menu each time. For example, modeless dialog 
boxes are often used with a text-search command in word-processing 
applications. The dialog box remains displayed while the search is carried 
out. The user can then return to the dialog box and search for the same 
hes again, or change the entry in the dialog box and search for a new 
word. 


An application with a modeless dialog box processes messages for that box 
by using the IsDialogMessage function. 


The dialog function of a modeless dialog box must send a message to the 
parent window when it has input for the parent window. It must also 
destroy the dialog box when it is no longer needed. A dialog box can 

be destroyed by using the Destroy Window function. 
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2.2.7.6 Modal Dialog Box 


A modal dialog box requires the user to respond to a request before the 
application continues. Typically, a modal dialog box is used when a com- 
mand has been chosen that needs additional information before it can 
proceed. The user should not be able to continue some other operation 
unless the command is canceled or additional information is provided. 


A modal dialog box disables its parent window, and it creates its own mes- 
sage loop, temporarily taking control of the application queue away from 
the main loop of the program. A modal dialog box is displayed when the 
application calls the DialogBox function. 


The dialog box is displayed until the dialog function calls the EndDialog 
function, or until Windows is terminated. The parent window remains 
disabled unless the dialog box enables it. Note that enabling the parent 
window is not recommended since it defeats the purpose of the modal 
dialog box. 


2.2.7.7 System-Modal Dialog Box 


A system-modal dialog box is identical to a modal dialog box except that 
all windows, not just the parent window, are disabled. System-modal dia- 
log boxes must be used with care since they effectively shut down the sys- 
tem until the user supplies the required information. 


2.2.7.8 Dialog-Box Keyboard Interface 


Windows provides a special keyboard interface for modal and modeless 
dialog boxes that use the IsDialogMessage function to filter messages. 
This keyboard interface carries out special processing for several keys and 
generates messages that correspond to certain buttons in the dialog box or 
changes the input focus from one control to another. Table 2.7 lists the 
keys used in this interface and the respective action: 
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Table 2.7 
Dialog-Box Keyboard Interface 


Key Action 

DOWN Moves the input focus to the next control 
that has the WS_ GROUP style. 

ENTER Sends a WM. COMMAND message to the 


dialog function. The wParam parameter is 
set to 1 or the default button. 


ESCAPE Sends a WM_ COMMAND message to the 
dialog function. The wParam parameter is 
set to 2. 

LEFT Same as UP. 

RIGHT Same as DOWN. 


SHIFT+TAB Moves the input focus to the previous 
control that has the WS.. TABSTOP style. 


TAB Moves the input focus to the next control 
that has the WS_ TABSTOP style. 
UP Moves the input focus to the previous 


control that has the WS. GROUP style. 


The TAB and DIRECTION keys have no effect if the controls in the dialog box 
do not have the WS_ TABSTOP or WS_. GROUP style. The keys have no 
effect in a modeless dialog box if the IsDialogMessage function 1s not 
used to filter messages for the dialog box. 


For applications that use accelerators and have modeless dialog 
boxes, the IsDialogMessage function must be called before the 
TranslateAccelerator function. Otherwise, the keyboard interface 
for the dialog box may not be processed correctly. 


Applications that have modeless dialog boxes and want those boxes to 
have the special keyboard interface must filter all messages retrieved from 
the application queue through the IsDialogMessage function before car- 
rying out any other processing. This means that the application must pass 
the message to the function immediately after retrieving the message by 
using the GetMessage or PeekMessage function. Most applications 
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that have modeless dialog boxes incorporate the IsDialogMessage 
function as part of the main message loop in the WinMain function. The 
IsDialogMessage function automatically processes any messages for the 
dialog box. This means that if the function returns a nonzero value, the 
message does not require additional processing and must not be passed to 
the TranslateMessage or DispatchMessage function. 


The IsDialogMessage function also processes the ALT+mnemonic 
sequence. 


2.2.7.9 Scrolling in Dialog Boxes 


In modal dialog boxes, the cursor keys have specific functions that depend 
on the controls in the box. For example, the keys move the input focus 
from control to control in group boxes, move the cursor in edit controls, 
and scroll the contents of list boxes. The cursor keys cannot be used to 
scroll the contents of any dialog box that has its own scroll bars. If a dia- 
log box has scroll bars, the application must provide an appropriate key- 
board interface for the scroll bars. Note that the mouse interface for 
scrolling is available if the system has a mouse. 


2.2.7.10 Dialog-Box Measurements 


Dialog box and control dimensions and coordinates are device-indepen- 
dent. Since a dialog box may be displayed on system displays that have 
widely varying pixel resolutions, dialog-box dimensions are specified in sys- 
tem character widths and heights instead of pixels. Characters are guar- 
anteed to give the best possible appearance for a given display. One unit in 
the x direction is equal to one-fourth of a system character width. One 
unit in the y direction is equal to one-eighth of a system character height. 
Applications can convert these measurements to pixels by using the 
MapDialogRect function. 


Windows does not allow the height of a dialog box to exceed the height of 
the client area or the height of a full screen window. The width of a dialog 
box is not allowed to be greater than the width of the screen. 


2.2.¢.11 Return Values from a Dialog Box 


The DialogBox function that creates a modal dialog box does not return 
until the dialog function has called the EndDialog function to signal the 
end of the dialog box. When control finally returns from the DialogBox 
function, the return value is equal to the value specified in the EndDialog 
function. This means a modal dialog box can return a value through the 
EndDialog function. 
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Modeless dialog boxes cannot return values in this way since they do not 
use the EndDialog function to terminate execution and do not return 
control in the same way a modal dialog box does. Instead, modeless dialog 
boxes return values to their parent windows by using the SendMessage 
function to send a notification message to the parent window. Although 
Windows does not explicitly define the content of a notification message, 
most applications use a WM_~COMMAND message with an integer value 
that identifies the dialog box in the wParam parameter and the return 
value in the ‘Param parameter. Modal dialog boxes may also use this tech- 
nique to return values to their parent windows before terminating. meas- 
urements 


2.2.7.12 Controls in a Dialog Box 


A dialog box can contain any number and any type of controls. A control 
is a child window that belongs to a predefined or application-defined win- 
dow class and that gives the user a method of supplying input to the appli- 
cation. Most dialog boxes contain one or more controls of the predefined 
class. The number of controls, the order in which they should be created, 
and the location of each in the dialog box are defined by the control state- 
ments given in the dialog-box template. 


2.2.7.13 Control Identifiers 


Every control in a dialog box needs a unique control identifier, or ID, to 
distinguish it from other controls. Since all controls send information 

to the dialog function through WM_ COMMAND messages, the control 
identifiers are essential for the dialog box to determine which control sent 
a given message. 


All identifiers for all controls in the dialog box must be unique. If a dialog 
box has a menu, there must be no conflict between menu-item identifiers 
and control identifiers. Since Windows sends menu input to a dialog func- 
tion as WM_ COMMAND messages, conflicts with menu and control 
identifiers can cause errors. 


The dialog function usually identifies the dialog-box controls by using 
their control identifier. Occasionally the dialog function requires the win- 
dow handle that was given to the control when it was created. The dialog 
nee can retrieve this window handle by using the GetDlgItem 
unction. 
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2.2.7.14 Control Styles 


The WS. TABSTOP style specifies that the user can move the input focus 
to the given control by pressing the TAB or SHIFT+TAB keys. Typically, 
every control in the dialog box has this style, so the user can move the 
input focus from one control to the other. If two or more controls are in 
the dialog box, the TAB key moves the input focus to the controls in the 
order in which they have been created. The SHIFT+TAB keys move the input 
focus in reverse order. For modal dialog boxes, the TAB and SHIFT+TAB 
keys are automatically enabled for moving the input focus. For modeless 
dialog boxes, the IsDialogMessage function must be used to filter mes- 
sages for the dialog box and to process these keystrokes. Otherwise, the 
keys have no special meaning and the WS_ TABSTOP style is ignored. 


The WS_ GROUP style specifies that the user can move the input focus to 
the given control by using a DIRECTION key. Typically, the first and last 
controls in a group of consecutive controls in the dialog box have this 
style, so the user can move the input focus from one control to the other. 
The DOWN and RIGHT keys move the input focus to controls in the order in 
which they have been created. The UP and LEFT keys move the input focus 
in reverse order. For modal dialog boxes, the DIRECTION keys are automati- 
cally enabled for moving the input focus. For modeless dialog boxes, the 
IsDialogMessage function must be used to filter messages for the dialog 
box and to process these keystrokes. Otherwise, the keys have no special 
meaning and the WS_ GROUP style is ignored. 


2.27.15 Buttons in a Dialog Box 


Button controls are the principal interface of a dialog box. Almost all 
dialog boxes have at least one push-button control and most have one 
default push button and one or more other push buttons. Many dialog 
boxes have collections of radio buttons enclosed in group boxes, or lists 
of check boxes. 


Most modal or modeless dialog boxes that use the special keyboard inter- 
face have a default push button whose control identifier is set to 1 so that 
the action the dialog function takes when the button is clicked is identical 
to the action taken when the ENTER key is pressed. There can be only one 
button with the default style; however, an application can assign the 
default style to any button at any time. These dialog boxes may also set 
the control identifier of another push button to 2 so that the action of the 
ESCAPE key is duplicated by clicking that button. 


When a dialog box first starts, the dialog function can set the initial state 


of the button controls by using the CheckDl]gButton function, which 
sets or clears the button state. This function is most useful when used to 
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set the state of radio buttons or check boxes. If the dialog box contains a 
group of radio buttons in which only one button should be set at any given 
time, the dialog function can use the CheckRadioButton function to set 
the button and automatically clear any other radio button. 


Before a dialog box terminates, the dialog function can check the state of 
each button control by using the IsDlgButtonChecked function, which 
returns the current state of the button. A dialog box typically saves this 
mee gee to initialize the buttons the next time the dialog box is 
created. 


2.2.7.16 Edit Controls in a Dialog Box 


Many dialog boxes have edit controls that let the user supply text as 
input. Most dialog functions initialize an edit control when the dialog box 
first starts. For example, the function may place a proposed filename in 
the control that the user can adapt or modify. The dialog function can set 
the text in an edit control by using the SetDl]gItem Text function, which 
copies text in a given buffer to the edit control. When the edit control 
receives the input focus, the complete text will automatically be selected 
for editing. 


Since edit controls do not automatically return their text to the dialog 
box, the dialog function must retrieve the text before terminating. I[t can 
retrieve the text by using the GetDlgItem Text function, which copies 
the edit-control text to a buffer. The dialog function typically saves this 
text to initialize the edit control later, or passes it on to the parent win- 
dow for processing. 


Not all edit controls are used for text. Some dialog boxes use edit controls 
that let the user enter numbers. The dialog function can retrieve a num- 
ber from an edit control by using the GetDlgItemInt function, which 
retrieves the text of the control and converts the text to a decimal value. 
The user enters the number in decimal digits. It can be either signed 

or unsigned. The dialog function can display an integer by using the 
SetDlgItemInt function. It converts a signed or unsigned integer to 

a string of decimal digits. 


2.2.7.17 List Boxes and Directory Listings 


Some dialog boxes display lists, such as filenames, from which the user can 
select one or more names. Dialogs boxes that display a list typically use 
list-box controls. Dialog boxes that display a list of filenames typically use 
a list-box control and the DigDirList and DlgDirSelect functions. The 
DigDirList automatically fills a list box with the filenames in the current 
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directory. The DigDirSelect function retrieves the selected filename from 
the list box. Together they provide a convenient way for a dialog box to 
display a directory listing and let the user select a file without having to 
type in the name of the directory and file. 


2.2.7.18 Messages for Dialog-Box Controls 


Many controls recognize predefined messages that, when sent to the 
control, cause it to carry out some action. A dialog function can send 
a message to a control by supplying the control identifier and using 
the SendDlgItemMessage function, which is identical to the 

Send Message function except that it uses a control identifier instead 
of a window handle to identify the control that is to receive the 
message. 


2.2.8 Scrolling Functions 


Scrolling functions control the scrolling of a window’s contents and con- 
trol the window’s scroll bars. Scrolling is the movement of data in and out 
of the client area at the request of the user. It is a way for the user to see a 
document or graphic in parts if Windows cannot fit the entire document or 
graphic inside the client area. A scroll bar allows the user to control scroll- 
ing. The following list briefly describes each scrolling function: 


Function Description 

GetScrollPos Retrieves the current position of the scroll-bar 
thumb. 

GetScrollRange Copies the minimum and maximum scroll-bar 


positions for given scroll-bar positions for a 
specified scroll. 


ScrollDC Scrolls a rectangle of bits horizontally and 
vertically. 

ScrollWindow Moves the contents of the client area. 

SetScrollPos Sets the scroll-bar thumb. 

SetScrollRange Sets the minimum and maximum scroll-bar 
positions. 

ShowScrollBar Displays or hides a scroll bar and its controls. 
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2.2.8.1 Processing Scroll Messages 


A window that permits scrolling needs a standard scroll bar or a scroll-bar 
control to let the user generate scrolling requests, and a window function 
to process the WM. HSCROLL and WM_ VSCROLL messages that 
represent the scrolling requests. Although the result of a scrolling request 
is entirely up to the window, a window typically carries out a scroll by 
moving in some direction from the current location or to a known begin- 
ning or end, and by displaying the data at the new location. For example, 
a word-processing application can scroll to the next line, the next page, or 
to the end of the document. 


2.2.8.2 Standard Scroll Bars and Scroll-Bar Controls 


A standard scroll bar is a part of the non-client area of a window. It is 
created with the window and displayed when the window is displayed. The 
sole purpose of a standard scroll bar is to let users generate scrolling re- 
quests for the window’s client area. A window has standard scroll bars if it 
is created with the WS_ VSCROLL or WS_HSCROLL style. A standard 
scroll bar is either vertical or horizontal. A vertical bar always appears at 
the right of the client area; a horizontal bar always appears at the bottom. 
A standard scroll bar always has the standard scroll-bar height and width 
as defined by the SM_CXVSCROLL and SM_ CYHSCROLL system metric 
values (for more information, see the GetSystemMetrics function in 
Chapter 3, “Functions Directory”). 


A scroll-bar control is a control window that looks and acts like a stan- 
dard scroll bar. But unlike a standard scroll bar, a scroll-bar control is not 
part of any window. As a separate window, a scroll-bar control can receive 
the input focus, and indicates this by displaying a flashing caret in the 
thumb. When a scroll-bar control has the input focus, the user can use the 
keyboard to direct the scrolling. Unlike standard scroll] bars, a scroll-bar 
control provides a built-in keyboard interface. Scroll-bar controls also can 
be used for other purposes. For example, a scroll-bar control can be used 
eo values from a range of values, such as a color from a rainbow of 
colors. 


2.2.8.3 Scrolling Requests 


A user makes a scrolling request by clicking in a scroll bar. Windows sends 
the request to the given window in the form of WM HSCROLL and 

WM VSCROLL messages. The [Param parameter contains a position 
value and the handle of the scroll-bar control that generated the message 
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({Param is zero if a standard scroll bar generated the message). The 
wParam parameter specifies the type of scroll, such as scroll up one line, 
scroll down a page, or scroll to the bottom. The type of scroll is deter- 
mined by which area of the scroll bar the user clicks. 


The user can also make a scrolling request by using the scroll-bar thumb, 
the small rectangle inside the scroll bar. The user moves the thumb by 
moving the mouse while holding the left mouse button down when the 
cursor is in the thumb. The scroll bar sends SB- THUMBTRACK 

and SB_ THUMBPOSITION flags with a WM_ HSCROLL or 

WM_ VSCROLL message to an application as the user moves the 

thumb. Each message specifies the current position of the thumb. 


2.2.8.4 Scrolling 


The simplest way to scroll is to erase the current contents of the chent 
area, and then paint the new information. This is the method an applica- 
tion is likely to use with SB_PAGEUP, SB. PAGEDOWN, SB_ TOP, and 
SB..END requests where completely new contents are required. 


For some requests, such as SB_ LINEUP and SB_LINEDOWN, not all the 
contents need to be erased, since some will still be visible after the scroll. 
The ScrollWindow function preserves a portion of the client-area’s con- 
tents, moves the preserved portion the specified amount, and prepares the 
rest of the client area for painting new information. ScrollWindow uses 
the BitBlt function to move a specific part of the client area to a new 
location within the client area. Any part of the client area that is 
uncovered (not in the part to be preserved) is invalidated and will be 
erased and painted over at the next WM_PAINT message. 


ScrollWindow also lets an application clip a part of the client area from 
the scroll. This is to keep items that have fixed positions in the client area, 
such as child windows, from moving. This action automatically invalidates 
the part of the client area that is to receive the new information so that 
the application does not have to compute its own clipping regions. 


2.2.8.5 Scroll-Bar Thumb 


The scroll-bar thumb is the small rectangle in a scroll bar. It shows the 
approximate location within the current document or file of the data 
currently displayed in the client area. For example, the thumb is in the 
middle of the scroll bar when page three of a five-page document is in 
the client area. 
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The SetScrollPos function sets the thumb position in a scroll bar. Since 
Windows does not automatically update the thumb position when an 
application scrolls, SetScrollPos must be used to update the thumb posi- 
tion. The GetScrollPos function retrieves the current position. 


A thumb position is an integer. The position is relative to the left or upper 
end of the scroll bar, depending on whether the scroll bar is horizontal or 
vertical. The position must be within the scroll-bar range, which is defined 
by minimum and maximum values. The positions are distributed equally 
along the scroll bar. For example, if the range is 0 to 100, there are 100 
positions along the scroll bar, each equally spaced so that position 50 is in 
the middle of the scroll bar. The initial range depends on the scroll bar. 
Standard scroll bars have an initial range of 0 to 100; scroll-bar controls 
have an empty range (both minimum and maximum values are zero) if no 
explicit range is given when the control is created. The SetScrollRange 
function sets new minimum and maximum values so that applications can 
change the range at any time. The GetScrollRange function retrieves 
the current minimum and maximum values. The minimum and maximum 
values can be any integers. For example, a spreadsheet program with 

255 rows can set the vertical scroll range to 1 to 255. 


If SetScrollPos specifies a position value that is less than the minimum or 
more than the maximum, the minimum or maximum value is used instead. 
SetScrollPos moves the thumb along the thumb positions. 


2.2.8.6 Hiding a Standard Scroll Bar 


For standard scroll bars, if the minimum and maximum values are equal, 
the scroll bar is considered disabled and is hidden. This is the way to tem- 
porarily hide a scroll bar when it is not needed for the current contents of 
the client area. 


The SetScrollRange function hides and disables a standard scroll bar 
when it sets the minimum and maximum values to equal values. No 
scrolling requests can be made through the scroll bar when it 1s hidden. 
SetScrollRange enables the scroll bar and shows it again when it sets the 
minimum and maximum values to unequal values. The ShowScrollBar 
function can also be used to hide or show a scroll bar. It does not affect the 
scroll bar’s range or thumb position. 
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2.2.9 Menu Functions 


Menu functions create, modify, and destroy menus. A menu is an input 
tool in a Windows application that offers users two or more choices, which 
they can select with the mouse or keyboard. The following list briefly 


describes each menu function: 


Function 


ChangeMenu 
CheckMenultem 


CreateMenu 
DestroyMenu 
DrawMenuBar 
EnableMenultem 
GetMenu 


GetMenultemCount 
GetMenultemID 
GetMenuState 
GetMenuString 
GetSubMenu 


GetSystemMenu 


HiliteMenultem 
LoadMenulndirect 
SetMenu 


Description 
Appends, inserts, deletes, or modifies a menu 
item. 


Places or removes checkmarks next to pop- 
up menu items. 


Creates an empty menu. 

Destroys the specified menu. 

Redraws a menu bar. 

Enables, disables, or grays a menu item. 


Retrieves a handle to the menu of a specified 
window. 


-Returns the count of items in a menu. 


Returns the item’s identification. 
Obtains the status of a menu item. 
Copies a menu label into a string. 


Retrieves the menu handle of a pop-up 
menu. 


Accesses the system menu for copying and 
modification. 


Makes a top-level menu visible or invisible. 
Loads a menu resource. 


Specifies a new window menu. 
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2.2.10 Information Functions 


Information functions obtain information about the number and position 
of windows on the screen. The following list briefly describes each informa- 
tion function: 


Function Description 

AnyPopup Indicates whether the pop-up window is 
visible. 

ChildWindowFromPoint Determines which child window con- 
tains a specific point. 

EnumChildWindows Enumerates the child windows that 
belong to a specific parent window. 

Enum Task Windows Enumerates all windows associated 
with a task. 

Enum Windows Enumerates windows on the display. 

Find Window Returns the handle of a window with 
the given class and caption. 

GetNext Window Returns a handle to the next or 
previous window. 

GetParent Retrieves the handle of the specified 
window’s parent window. 

Get TopWindow Returns a handle to the top-level child 
window. 

Get Window Returns a handle from the window 
manager’s list. 

Get Window Task Returns the handle of a task associated 
with a window. 

IsWindow Determines whether a window is a 
valid, existing window. 

SetParent Changes the parent window of a child 
window. 

WindowF romPoint Identifies the window containing a 


specified point. 
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Functions Overview 


System functions return information about the system metrics, color, and 
time. The following list briefly describes each system function: 


Function 


GetCurrentTime 


GetSysColor 
GetSystem Metrics 


SetSysColors 


Description 

Returns the time elapsed since the sys- 
tem was booted. 

Retrieves the system color. 


Retrieves information about the system 
metrics. 


Changes one or more system colors. 


2.2.12 Clipboard Functions 


Chipboard functions carry out data interchange between Windows applica- 
tions. The clipboard is place for this interchange; it provides a place from 
which applications can pass data handles to other applications. The fol- 
lowing list briefly describes each clipboard function: 


Function 


CloseClipboard 
EmptyClipboard 


EnumClipboardFormats 


GetClipboardData 
GetClipboardFormatName 
GetClipboardOwner 


GetClipboard Viewer 
IsClipboardFormatAvailable 


OpenClipboard 
SetClipboardData 
SetClipboard Viewer 


Description 


Closes the clipboard. 


Empties the clipboard and reassigns 
clipboard ownership. 


Enumerates the available clipboard 
formats. 


Retrieves data from the clipboard. 
Retrieves the clipboard format. 


Retrieves the window handle associated 
with the current clipboard owner. 


Retrieves the handle of the first window 
in the clipboard viewer chain. 


Returns TRUE if the data in the given 
format is available. 


Opens the clipboard. 
Copies a handle for data. 


Adds a handle to the clipboard viewer 
chain. 
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2.2.13 Error Functions 


Error functions display errors and prompt the user for a response. The fol- 
lowing list briefly describes each error function: 


Function Description 

Flash Window Flashes the window by inverting its 
active/inactive state. 

MessageBeep Generates a beep on the system speaker. 

MessageBox Creates a window with the given text and 
caption. 


2.2.14 Caret Functions 


Caret functions affect the Windows system caret, which is a flashing line, 
block, or bitmap that marks a location in a window’s client area. The 
caret is especially useful in word-processing applications to mark a loca- 
tion in text for keyboard editing. These functions create, destroy, display, 
hide, and alter the blink time of the caret. The following list briefly 
describes each caret function: 


Function Description 

CreateCaret Creates a caret. 

DestroyCaret Destroys the current caret. 
GetCaretBlink Time Returns the caret flash rate. 
GetCaretPosition Returns the current caret position. 
HideCaret ‘Removes a caret from a given window. 
SetCaretBlinkTime Establishes the caret flash rate. 
SetCaretPos Moves a caret to the specified position. 
ShowCaret Displays the newly created caret or 


redisplays a hidden caret. 
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2.2.14.1 Creating and Displaying a Caret 


Windows forms a caret by inverting the pixel color within the rectangle 
given by the caret’s position and its width and height. Windows flashes 
the caret by alternately inverting the display, and then restoring it to its 
previous appearance. The caret blink time (in milliseconds) defines the 
elapsed time between inverting and restoring the display. A complete flash 
(on-off-on) takes twice the blink time. 


The CreateCaret function creates the caret shape and assigns ownership 
of the caret to the given window. The caret can be solid or gray, or, for 
bitmap carets, any desired pattern. The caret can have any shape, but 
typical shapes are a line, a solid block, a gray block, and a pattern, as 
shown in Figure 2.1: 


Underline Solid block 
Vertical line| Gray block? 
Bitmap & 


Figure 2.1 Caret Shapes 


Windows displays a solid caret by inverting everything in the rectangle 
defined by the caret’s width and height. For a gray caret, Windows inverts 
every-other pixel. For a pattern, Windows inverts only the white bits of 
the bitmap that defines the pattern. The width and height of a caret are 
given in logical units, which means they are subject to the window’s map- 
ping mode. 


2.2.14.2 Sharing the Caret 


There is only one system caret, so only one caret shape can be active at a 
time. Applications must cooperatively share the caret to prevent undesired 
effects. Windows does not inform an application when a caret is created or 
destroyed, so to be cooperative a window should create, move, show, and 
hide a caret only when it has the input focus or is active. A window should 
destroy the caret before losing the input focus or becoming inactive. 
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Bitmaps for the system caret can be created by using the CreateBitmap 
function, or loaded from the application’s resources by using the Load- 
Bitmap function. Bitmaps loaded from resources can be created by using 
the IconEdit program and added to an application’s resources by using 
the re resource compiler (for more information about re, see the Microsoft 
Windows Programming Tools). 


2.2.15 Cursor Functions 
Cursor functions set, move, show, hide, and confine the system cursor. The 


system cursor is a bitmap, displayed on the display screen, that shows a 
current location. The following list briefly describes each cursor function: 


Function Description 

ClipCursor Restricts the mouse cursor to a given rectangle. 

GetCursorPos Stores the mouse cursor position (in screen 
coordinates). 

LoadCursor Loads a cursor from the resource file. 

SetCursor Sets the cursor shape. 

SetCursorPos Sets the position of the mouse cursor. 

ShowCursor Increases or decreases the cursor display count. 


2.2.15.1 Pointing Devices and the Cursor 


When a system has a mouse (or any other type of pointing device), the 
cursor shows the current location of the mouse. Windows automatically 
displays and moves the cursor when the mouse is moved. If a system does 
not have a mouse, Windows does not automatically display or move 

the cursor. Applications can use the cursor functions to display or move 
the cursor when a system does not have a mouse. 


2.2.15.2 Creating a Custom Cursor 


The SetCursor function sets the cursor shape and draws the cursor. 
When a system has a mouse, Windows automatically changes the shape of 
the cursor when it crosses a window border or enters a different part of a 
window, such as a title or menu bar. It uses standard cursor shapes for 
the different parts of the screen, such as a pointer in a title bar. The 
SetCursor function lets an application delete the standard cursor and 
draw its own custom cursor. The cursor keeps its new shape until the 
mouse moves or a system command Is carried out. 
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2.2.15.3 Displaying and Hiding the Cursor 


In a system without a mouse, Windows does not display or move the cur- 
sor unless the user chooses certain system commands, such as commands 
for sizing and moving. This means that after a call to SetCursor, the cur- 
sor remains on the screen until a subsequent call to SetCursor with a 
NULL parameter removes the cursor, or until a system command is carried 
out. Applications that wish to use the cursor without a mouse usually 
simulate mouse input by using keyboard keys, such as the DIRECTION keys, 
and display and move the cursor by using the cursor functions. 


The ShowCursor function shows or hides the cursor. It is used to tem- 
porarily hide the cursor, and then restore it without changing the current 
cursor shape. This function actually sets an internal counter that deter- 
mines whether or not the cursor should be drawn. Hiding and showing are 
accumulative, so hiding the cursor five times requires that it be shown five 
times before the cursor will be drawn. 


2.2.15.4 Positioning the Cursor 


The SetCursorPos and GetCursorPos functions set and retrieve the 
current screen coordinates of the cursor. Although the cursor can be set 
at a location other than the current mouse location, if the system has a 
mouse, the next mouse movement will redraw the cursor at the mouse 
location. The SetCursorPos and GetCursorPos functions are most 
often used in applications that use the keyboard and specified keystrokes 
to move the cursor. Notice that screen coordinates are not affected by the 
mapping mode in a window’s client area. 


2.2.15.5 Confining the Cursor 


The ClipCursor function confines the cursor to a given rectangle on the 
display screen. The cursor can move to the edge of the rectangle but can- 
not move out of it. ClipCursor is typically used to restrict the cursor to a 
given window such as a dialog box that contains a warning about a serious 
error. The rectangle is always given in screen coordinates and does not 
have to be within the window of the currently running application. 


A cursor has a hotspot. The hotspot is the point in the cursor bitmap that 
has been explicitly selected to be the hotspot. When Windows draws the 
cursor, it always places the hotspot over the point on the display screen 
that represents the current position of the mouse or keyboard DIRECTION 
key. For example, the hotspot on the pointer is the point at the tip of the 
arrow. 
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2.2.16 Hook Functions 


Hook functions manage system hooks, which are shared resources that 
install a specific type of filter function. A filter function is an application- 
supplied callback function, specified by the Set WindowsHook function, 
that processes events before they reach any application’s message loop. 
Windows sends messages generated by a specific type of event to filter 
functions installed by the same type of hook. The following list briefly 
describes each hook function: 


Function | Description 

DefHookProc Calls the next filter function in a filter- 
function chain. 

Set WindowsHook Installs a system and/or application 
filter function. 

UnhookWindowsHook Removes a Windows filter function 


from a filter-function chain. 


2.2.16.1 Filter-Function Chain 


A filter-function chain is a series of connected filter functions for a particu- 
lar system hook. For example, all keyboard filter functions are installed by 
WH KEYBOARD and all journaling-record filter functions are installed 
by WH_ JOURNALRECORD. Applications pass these filter functions to 
the system hooks with calls to the Se} WindowsHook function. Each call 
adds a new filter function to the beginning of the chain. Whenever an 
application passes a filter function to a system hook, 1t must reserve space 
for the address of the next filter function in the chain. Ses} WindowsHook 
returns this address. 


Once each filter function completes its task, it must call the DefHook- 
Proc function. DefHookProc uses the address stored in the location 
reserved by the application to access the next filter function in the chain. 


To remove a filter function from a filter chain, an application must call the 


UnhookWindowsHook function with the type of hook and a pointer to 
the function. | 
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There are five types of standard window hooks and two types of debugging 
hooks. Table 2.8 lists each type and describes its purpose: 


Table 2.8 

System Hooks 
Type 

WH_ CALLWNDPROC 
WH_ GETMESSAGE 


WEL JOURNALRECORD 
WH. JOURNALPLAYBACK 
WHL_ KEYBOARD 

WH_ MSGFILTER 

WHL_ SYSMSGFILTER 


Note 


Purpose 


Installs a window function filter 
(on debugging versions only). 


Installs a message filter 
(on debugging versions only). 


Installs a journaling record filter. 
Installs a journaling playback filter. 
Installs a keyboard filter. 

Installs a message filter. 

Installs a system-wide message filter. 


The WH CALLWNDPROC and WH- GETMESSAGE hooks will affect 
system performance. They are supplied for debugging purposes only. 


2.2.16.2 Installing a Filter Function 


To install a filter function, an application must do the following: 


Export the function in its module definition file. 


2. Obtain the function’s address by using the MakeProcInstance 


function. 


3. Call the Set WindowsHook function, specifying the type of hook 
function ae Table 2.8) and the address of the function (returned 
by MakeProcInstance). 


4. Store the return value from SetWindowsHook in a reserved loca- 
tion. This value is the address of the previous filter function. 
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2.2.17 Property Functions 


Property functions create and access a window’s property list. A property 
list is a storage area that contains handles for data that the application 
wishes to associate with a window. The following list briefly describes each 
property function: 


Function Description 

EnumProps Passes the properties of a window to an enumera- 
tion function. 

GetProp Retrieves a handle associated with a string from the 
window property list. 

RemoveProp Removes a string from the property list. 

SetProp Copies a string and a data handle to a window's 


property list. 


2.2.17.1 Using Property Lists 


Once a data handle is in a window’s property list, any application can 
access the handle if it can also access the window. This makes the property 
list a convenient way to make data (for example, alternate captions or 
menus for the window) available to the application when it wishes to 
modify the window. 


Every window has its own property list. When the window is created, the 
list is empty. The SetProp function adds entries to the list. Each entry 
contains a unique ANSI string and a data handle. The ANSI string 
identifies the handle; the handle identifies the data associated with the 
window, as illustrated in Figure 2.2: 


ANSI String Handle 


Figure 2.2 Property List 
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The data handle can identify any object or memory block that the applica- 
tion wishes to associate with the window. The GetProp function retrieves 
the data handle of an entry from the list without removing the entry. The 
handle can then be used to retrieve or use the data. The RemoveProp 
function removes an entry from the list when it is no longer needed. 


Although the purpose of the property list is to associate data with a win- 
dow for use by the application that owns the window, the handles in a pro- 
perty list are actually accessible to any application that has access to the 
window. This means an application can retrieve and use a data handle 
from the property list of a window created by another application. But 
using another application’s data handles must be done with care. Only 
shared, global memory objects, such as GDI drawing objects, can be used 
by other applications. If a property list contains local or global memory 
handles or resource handles, only the application that has created the win- 
dow may use them. Global memory handles can be shared with other 
applications by using the Windows clipboard (for more information, see 
Section 2.2.12). Local memory handles cannot be shared. 


The contents of a property list can be enumerated by using the 
EnumProps function. The function passes the string and data han- 
dle of each entry in the list to an application-supplied function. The 
application-supplied function can carry out any task. 


The data handles in a property list always belong to the application that 
created them. The property list itself, like other window-related data, 
belongs to Windows. A window’s property list is actually allocated in the 
user heap, the local heap of the user library. Although there is no defined 
limit to the number of entries in a property list, the actual number of 
entries depends on how much room is available in the user heap. This 
depends on how many windows, window classes, and other window-related 
objects have been created. 


The application creates the entries in a property list. Before a window is 
destroyed or the application that owns the window terminates, all entries 
in the property list must be removed by using the RemoveProp function. 
Failure to remove the entries leaves the property list in the user heap and 
makes the space it occupies unusable for subsequent applications. This can 
ultimately cause a user-heap overflow. Entries in the property list can be 
removed at any time by using the RemoveProp function. If there are 
entries in the property list when the WM. DESTROY message is received 
for the window, the entries must be removed at that time. To ensure that 
all entries are removed, use the EnumProps function to enumerate all 
entries in the property list. 
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2.2.18 Rectangle Functions 


Rectangle functions alter and obtain information about rectangles in a 
window’s client area. In Windows, a rectangle is defined by a RECT data 
structure. The structure contains two points: the upper-left and lower- _ 
right corners of the rectangle. The sides of a rectangle extend from these - 
two points and are parallel to the » and yaxes. The following list briefly 
describes each rectangle function: 


Function Description 

CopyRect Makes a copy of an existing rectangle. 
EqualRect Determines whether two rectangles are equal. 
InflateRect Expands or shrinks the specified rectangle. 
IntersectRect _ Finds the intersection of two rectangles. 
OffsetRect Moves a given rectangle. 

PtInRect Indicates whether a specified point lies within a 


given rectangle. 
SetRectEmpty Sets a rectangle to an empty rectangle. 


UnionRect Stores the union of two rectangles. 


2.2.18.1 Using Rectangles in a Windows Application 


Rectangles are used to specify rectangular areas on the display or in a win- 
dow, such as the cursor clipping area, the client repaint area, a formatting 
area for formatted text, and the scroll area. Rectangles are also used to 
fill, frame, or invert an area in the client area with a given brush, and to 
retrieve the coordinates of a window or a window’s client area. 


Since rectangles are used for many different purposes, the rectangle func- 
tions do not use an explicit unit of measure. Instead, all rectangle coordi- 
nates and dimensions are given in signed, logical values. The actual units 
are determined by the function in which the rectangle is used. 


2.2.18.2 Rectangle Coordinates 
Coordinate values for a rectangle can be in the range -32,768 to 32,767. 


Widths and heights, which must be positive, are in the range 0 to 32. 767. ae. 
This means that a rectangle whose left and right sides or whose top and 
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bottom are further apart than 32,768 units is not valid. Figure 2.3 shows a 
rectangle whose upper-left corner Is left of the origin, but whose width is 
less than 32,767: 


(16000,2000) 


(-16000, -2000) 


SS eles 


Width = 16000 - (-16000) = 32000 < = 32767 


Figure 2.3 Rectangle Limits 


2.2.18.3 Additional Information 


The SetRect function creates a rectangle, the CopyRect function makes 
a copy of a given rectangle, and the SetRectEmpty function creates an 
empty rectangle. An empty rectangle is any rectangle that has zero width, 
zero height, or both zero width and height. 


The InflateRect function increases or decreases the width and height of 
a rectangle. It adds or removes width from both ends of the rectangle, or 
adds or removes height from both the top and bottom of the rectangle. 


The OffsetRect function moves the rectangle by a given amount. It moves 
the corners of the rectangle by adding the given x and y amounts to the 
corner coordinates. 


The PtInRect function determines whether a given point lies within a 
given rectangle. The point is in the rectangle if it lies on the left or top 
side or 1s completely within the rectangle. The IsRectEmpty function 
determines whether the given rectangle is empty. 
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The IntersectRect function creates a new rectangle that is the intersec- 
tion of two existing rectangles. The intersection is the largest rectangle 
contained in both existing rectangles. The intersection of two rectangles 
is shown in Figure 2.4: 


Rectangle 1 


[eee | 


Rectangle 2 


Figure 2.4 Intersection of Two Rectangles 


The UnionRect function creates a new rectangle that is the union of two 
existing rectangles. The union is the smallest rectangle that contains both 
existing rectangles. The union of two rectangles is shown in Figure 2.5: 


Figure 2.5 Union of Two Rectangles 


For information about functions that draw ellipses and polygons, see 
Section 2.3.9. 
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2.3 Graphics Device Interface 
Function Groups 


The graphics device interface (GDI) contains the functions that perform 
device-independent graphic operations within a Windows application, 
including creating a wide variety of line, text, and bitmap output on many 
output devices. 


2.3.1 Device-Context Functions 


Device-context functions create, delete, and restore device contexts (DC). 
A device context is a link between a Windows application, a device driver, 
and an output device, such as a printer or plotter. The following list 
briefly describes each device-context function: 


Function Description 

CreateCompatibleDC Creates a memory device context. 

CreateDC Creates a device context. 

CreateIC Creates an information context. 

DeleteDC Deletes a device context. 

RestoreDC Restores a device context. 

SaveDC Saves the current state of the device 
context. 


2.3.1.1 Device Contexts 


Figure 2.6 shows the flow of information from a Windows application 
through a device context and a device driver to an output device: 


Application 


- Device 
ue DEeVLCe— |-- driver 
context 


=  Dutput device 6 


Figure 2.6 Information Flow 
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Any Windows application can use GDI functions to access an output 
device. GDI passes calls (which are device-independent) from the applica- 
tion to the device driver. The device driver then translates the calls into 
device-dependent operations. 


2.3.1.2 Device-Context Attributes 


Device-context attributes describe selected drawing objects (pens and 
brushes), the selected font and its color, the way in which objects are 
drawn (or mapped) to the device, the area on the device available for 
output (clipping region), and other important information. The data 
structure that contains these attributes is called the DC data block. 


Table 2.9 lists the default device-context attributes and the GDI func- 
tions that affect or use these attributes: 


Table 2.9 


Default Device-Context Attributes and Related GDI Functions 


Attribute 


Background color 
Background mode 
Bitmap 


Brush 


Brush origin 


Chipping region 


Current pen position 


Drawing mode 
Font 


Intercharacter spacing 


Mapping mode 
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Default 


White 
OPAQUE 
No default 


WHITE_ BRUSH 


(0,0) 


Display surface 


(0,0) 
R2_ COPYPEN 
SYSTEM_ FONT 


MM_ TEXT 


GDI Functions 


SetBkColor 
SetBkMode 


CreateBitmap 
CreateBitmapIndirect 
CreateCompatibleBitmap 
SelectObject 


CreateBrushIndirect 
CreateHatchBrush 
CreatePatternBrush 
CreateSolidBrush 
SelectObject 


SetBrushOrg 
UnrealizeObject 


ExcludeClipRect 
IntersectClipRect 
OffsetClipRgn 
SelectClipRgn 


MoveTo 
SetROP2 


CreateFont 
CreateFontIndirect 
SelectObject 


Set TextCharacterExtra 
SetMapMode 
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Table 2.9 (continued) 


Attribute Default GDI Functions 
Pen BLACK _ PEN CreatePen 
CreatePenIndirect 
SelectObject 
Polygon-filing mode ALTERNATE SetPolyFillMode 
Relative-absolute flag ABSOLUTE SetRelAbs 
Stretching mode BLACKONWHITE ~~ SetStretchBltMode 
Text color Black SetTextColor 
Viewport extent (1,1) Set ViewportExt 
Viewport origin (0,0) Set ViewportOrg 
Window extent (1,1) Set WindowExt 
Window origin (0,0) Set WindowOrg 


2.3.1.3 Saving a Device Context 


Occasionally, it 1s necessary to save a device context so that the original 
attributes will be available at a later time. For example, a Windows appli- 
cation may need to save its original clipping region so that it can restore 
the client area’s original state after a series of alterations occur. The 
SaveDC and RestoreDC functions make this possible. 


2.3.1.4 Deleting a Device Context 


The DeleteDC function deletes a device context and ensures that shared 
resources are not removed until the last context is deleted. The device 
driver is a shared resource. 


2.3.1.5 Creating a Compatible Device Context 


The CreateCompatibleDC function causes Windows to treat a portion 
of memory as a virtual device. This means that Windows prepares a device 
context that has the same attributes as the device for which it was 
created, but the device context has no connected output device. To use the 
compatible device context, the application creates a compatible bitmap 
and selects it into the device context. Any output it sends to the device is 
drawn in the selected bitmap. Since the device context is compatible with 
some actual device, the context of the bitmap can be copied directly to 

the actual device, or vice versa. This also means that the application can 
send output to memory (prior to sending it to the device). Note that the 
CreateCompatibleDC function works only for devices that have BitBlt 
capabilities. 
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2.3.1.6 Information Contexts 


The CreateIC function creates an information context for a device. An 
information context is a device context with limited capabilities; it cannot 
be used to write to the device. An application uses an information context 
to gather information about the selected device. Information contexts are 
useful in large applications that require memory conservation. 


2.3.1.7 Obtaining Device Information 


By using an information context and the GetDeviceCaps function, you 
can obtain the following device information: 

e Device technology 

e Physical display size 

e Color capabilities of the device 

e Drawing objects available on the device 

e Clipping capabilities of the device 

e Raster capabilities of the device 

e Curve-drawing capabilities of the device 

e Line-drawing capabilities of the device 

e Polygon-drawing capabilities of the device 


e Text capabilities of the device 


2.3.2 Drawing-Tool Functions 


Drawing-tool functions create and delete the drawing tools that GDI uses 
when it creates output on a device or display surface. The following list 
briefly describes each drawing-tool function: 


Function Description 

CreateHatchBrush Creates a logical brush that has a 
hatched pattern. 

CreatePatternBrush Creates a logical brush that has a 
specified pattern. 

CreatePen Creates a logical pen. 

CreatePenIndirect Creates a logical pen. 
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CreateSolidBrush Creates a logical brush. 

DeleteObject Deletes a logical pen, brush, font, 
bitmap, or region. 

EnumObjects Enumerates the available pens or 
brushes. 

GetObject Copies the bytes of logical data that 
define an object. 

SelectObject Selects an object as the current 
object. 

UnrealizeObject Directs GDI to reset the origin of the 


given brush. 


2.3.2.1 Drawing-Tool Uses 


A Windows application can use any of three tools when it creates output: 
a bitmap, a brush, or a pen. An application can use the pen and brush 
together, outlining a region or object with the pen and filling the region’s 
or object’s interior with the brush. GDI allows the application to create 
pens with solid colors, bitmaps with solid or combination colors, and 
brushes with solid or combination colors (the available colors and color 
combinations depend on the capabilities of the intended output device). 


2.3.2.2 Brushes 


There are seven predefined brushes available in GDI; an application selects 
any one of them by using the GetStockObject function. The following 
list describes these brushes: 


e Black 

e Dark-Gray 
e Gray 

e Hollow 

e Light-Gray 
e Null 

e White 
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There are six hatched brush patterns; an application can select any one of 
these patterns by using the CreateHatchBrush function. (A hatch line is 
a thin line that appears at regular intervals on a solid background.) The 
following list describes these hatch patterns: 

e Backward Diagonal 

e Cross 

e Diagonal Cross 

e Forward Diagonal 

e Horizontal 

e Vertical 


Figure 2.7 shows each hatched brush pattern. A simple Windows applica- 
tion created this figure: 


HS_HORIZONTAL = HS_FOLAGONAL HS_BDIAGONAL 


= 7 \ 


HS_VERTICAL HS_CROSS HS_DIAGCROSS 


Figure 2.7 Hatched Brush Patterns 


2.3.2.6 Pens 


There are three predefined pens available in GDI; an application selects 
any one of them by using the GetStockObject function. The following 
list describes these pens: 


-e) Black 
e Null 
e White 
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In addition to selecting a stock pen, an application creates an original pen 
by using the GDI CreatePen function. This function allows the applica- 
tion to select one of five pen styles, a pen width, and a pen color (if the 
device has color capabilities), The pen style can be solid, dashed, dotted, 
a combination of dots and dashes, or null. The pen width is the number 
of logical units GDI maps to a certain number of pixels (this number is 
dependent on the current mapping mode if the pen is selected into a 
device context). The pen color is an RGB color value. 


Figure 2.8 shows a variety of pen patterns obtained from calls to the 
CreatePen function. A simple Windows application created this figure: 


Solid Line width of 1 
oe “Dot a Line width of ? 
Dash and dot _ Line width of 10 
Dash and two dots Line width of 13 


Figure 2.8 Pen Patterns 


2.3.2.4 Color 


Many of the GDI functions that create pens and brushes require that the 
calling application specify an RGB color value. The RGB color value is a 
long integer that contains a red, a green, and a blue color field. Each field 
specifies the intensity of the color: zero indicates the lowest intensity and 
255 indicates the highest. GDI passes the RGB color value that it receives 
as a function parameter to the output device driver, which selects the 
closest available color on the device. 


If the device is a plotter, the driver converts the RGB value to a single 
color that matches one of the pens on the device. 


If the device uses color raster technology and the RGB value specifies a 
color for a pen, the driver will select a solid color. If the device uses color 
raster technology and the RGB value specifies a color for a brush, the 
driver will select from a variety of available color combinations. (Most 
color raster devices offer 250,000 possible color patterns.) 
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If the device is monochrome (black-and-white), the driver will select black, 
white, or a shade of gray, depending on the RGB value. If the sum of the 
RGB values is zero, the driver selects a black brush. If the sum of the RGB 
values is 765, the driver selects a white brush. If the sum of the RGB 
ete between zero and 765, the driver selects one of the gray patterns 
available. 


2.3.3 Drawing-Attribute Functions 


Drawing-attribute functions affect the appearance of Windows output, 
which has four forms: line, brush, bitmap, and text. The following list 
describes each drawing-attribute function: 


Function Description 
GetBkColor Returns the current background color. 
GetBkMode Returns the current background mode. 
GetPolyFillMode Retrieves the current polygon-filling 
mode. | 
GetRelAbs Retrieves the relative-absolute flag. 
GetROP2 Retrieves the current drawing mode. 
GetStretchBltMode Retrieves the current stretching mode. 
Get TextColor Retrieves the current text color. 
SetBkColor Sets the background color. 
SetBkMode Sets the background mode. 
SetPolyFillMode Sets the polygon-filling mode. 
SetRelAbs Sets the relative-absolute flag. 
SetROP2 Sets the current drawing mode. 
SetStretchBltMode Sets the stretching mode. 
Set TextColor Sets the text color. 
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2.3.3.1 Background Mode and Background Color 


Line output can be solid or broken (dashed, dotted, or a combination of 
the two). If it is broken, the space between the breaks can be filled by set- 
ting the background mode to OPAQUE and selecting a color. By setting 
the background mode to TRANSPARENT, the space between breaks is 
left in its original state. The SetBkMode and SetBkColor functions 
accomplish this task. 


Brush output is solid, patterned, or hatched. The space between hatch 
marks can be filled by setting the background mode to OPAQUE and 
selecting a color. When Windows creates brush output on a display, it 
combines the existing color on the display surface with the brush color to 
yield a new and final color; this is a binary raster operation. If the default 
raster operation is not appropriate, a new one is chosen by using the 
SetROP2 function. 


2.3.3.2 Stretch Mode 


If an application copies a bitmap to a device and it is necessary to shrink 
or expand the bitmap before drawing, the StretchBlt function is useful. 


2.3.3.3 Text Color 


The appearance of text output is limited only by the number of available 
fonts and the color capabilities of the output device. The SetBkColor 
function sets the color of the text background (the unused portion of each 
character’s cell) and the SetTextColor function sets the color of the 
character itself. 


2.3.4 Mapping Functions 


Mapping functions alter and retrieve information about the GDI mapping 
modes. In order to maintain device independence, GDI creates output in a 
logical space and maps it to the display. The mapping mode defines the 
relationship between units in the logical space and pixels on a device. The 
following list briefly describes each mapping function: 
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Function 


GetMapMode 
Get ViewportExt 


Get ViewportOrg 
Get WindowExt 
Get WindowOrg 
Offset ViewportOrg 
Offset WindowOrg 
ScaleViewportExt 
ScaleWindowExt 
SetMapMode 


Set ViewportExt 
SetViewportOrg 
Set WindowExt 
Set WindowOrg 


Description 


Retrieves the current mapping mode. 


Retrieves a device context’s viewport 
extents. 


Retrieves a device context’s viewport origin. 
Retrieves a device context’s window extents. 
Retrieves a device context’s window origin. 
Modifies a viewport origin. 

Modifies a window origin. 

Modifies the viewport extents. 

Modifies the window extents. 


Sets the mapping mode of a specified device 
context. 


Sets a device context’s viewport extents. 
Sets a device context’s viewport origin. 
Sets a device context’s window extents. 


Sets a device context’s window origin. 


There are eight different mapping modes: MM_ ANISOTROPIC, 

MM HIENGLISH, MM_ HIMETRIC, MM. ISOTROPIC, 

MMW LOENGLISH, MM_~ LOMETRIC, MM_ TEXT, and MM_ TWIPS. 
Each mode has a specific use in a Windows application. In five of the 
modes, Windows maps logical units to distinct physical units, such as 
inches or millimeters; in another mode, Windows maps a logical unit to a 
pixel on the display; in the two other modes, Windows maps an arbitrary 
number of logical units to a pixel (this arbitrary number is defined in the 
application). Table 2.10 summarizes the eight GDI mapping modes: 
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Table 2.10 
GDI Mapping Modes 


Mapping Mode Intended Use 


MM_ANISOTROPIC Used in applications that map one logical unit to 
an arbitrary physical unit. The # and y-axes are 


arbitrarily scaled. 

MM_ HIENGLISH Used in applications that map one logical unit to 
0.001 inch. Positive y extends upward. 

MM... HIMETRIC Used in applications that map one logical unit to 
0.01 millimeter. Positive y extends upward. 

MM_ ISOTROPIC Used in applications that map one logical unit to an 


arbitrary physical unit. One unit along the z-axis is 
always equal to one unit along the y-axis. 


MM_ LOENGLISH Used in applications that map one logical unit to 


0.01 inch. Positive y extends upward. 


MM... LOMETRIC Used in applications that map one logical unit to 
0.1 millimeter. Positive y extends upward. 

MM_ TEXT - _Used in applications that map one logical unit to 
one pixel. Positive y extends downward. 

MM... TWIPS Used in applications that map one logical unit to 
1/1440 inch (1/20 of a printer’s Sane): Positive y 


extends upward. 


2.3.4.1 Constrained Mapping Modes 


GDI classifies six of the mapping modes as constrained mapping 

modes: MM_ HIENGLISH, MM_ HIMETRIC, MM_ LOENGLISH, 

MM. LOMETRIC, MM_ TEXT, and MM.. TWIPS. In each of these modes, 
one logical unit is mapped to a predefined physical unit. For instance, the 
MM. TEXT mode maps one logical unit to one device pixel, and the 
MM..LOENGLISH mode maps one logical unit to 0.01 inch on the device. 
These mapping modes are constrained because the scaling factor 1s fixed, 
so an application cannot change the number of logical units that Windows 
maps to a physical unit. Table 2.11 shows the number of logical units in 
various mapping modes that result in a certain physical unit: 
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Table 2.11 

Logical/Physical Conversion Table 
Mapping Logical Physical 
Mode Units Unit 

MM_ HIENGLISH 1000 1 inch 
MM... HIMETRIC 100 1 millimeter 
MM_LOENGLISH 100 1 inch 
MM_ LOMETRIC 10 1 millimeter 
MM_ TEXT 10 Device pixel 
MM_ TWIPS 1440 1 inch 


2.3.4.2 Partially Constrained and Unconstrained Modes 


The unconstrained mapping modes, MM_ ISOTROPIC and 

MM_ ANISOTROPIC, use two rectangular regions to derive a scaling 
factor and an orientation: the window and the viewport. The window 
lies within the logical-coordinate space and the viewport lies within 
the physical-coordinate space. Both possess an origin, an 2-extent, 

and a yextent. The origin may be any one of the four corners. The 
g-extent is the horizontal distance from the origin to its opposing 
corner. The yextent is the vertical distance from the origin to its oppos- 
ing corner. Windows creates a horizontal scaling factor by dividing 

the viewport’s z-extent by the window’s a-extent and creates a vertical 
scaling factor by dividing the viewport’s yextent by the window’s 
y-extent. These scaling factors determine the number of logical units 
that Windows maps to a number of pixels. In addition to determin- 
ing scaling factors, the window and viewport determine the orientation 
of an object. Windows always maps the window origin to the viewport 
origin, the window zextent to the viewport zextent, and the window 
y-extent to the viewport yextent. 
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Partially Constrained Mapping Mode 


An application creates output with equally scaled axes by using the 

MM. ISOTROPIC mapping mode. This means that Windows will map a 
symmetrical object (for example, a square or a circle) in the logical space 
as a symmetrical object in the physical space. In order to maintain this 
symmetry, GDI shrinks one of the viewport extents. The amount of shrink- 
age depends on the requested extents and the aspect ratio of the device. 
This mapping mode is called partially constrained because the application 
does not have complete control in altering the scaling factor. 


Unconstrained Mapping Mode 


An application can completely alter the horizontal and vertical scaling 
factors by using the MM_ ANISOTROPIC mapping mode and setting the 
window and viewport extents to any value after selecting this mapping 
mode. Windows will not alter either scaling factor in this mode. 


2.3.4.3 Transformation Equations 


GDI uses the following equations to transform logical points to device 
points, and device points to logical points: 
e Transforming logical points to device points: 


Dx = 1 — WO} Xx xVE/xWE + xVO 
Dy = (Ly — yWO) X yVE/yWE + yVO 


e Transforming device points to logical points: 


Lx = i — vO} xX xWE/xVE + xWO 
Ly = (Dy — yVO) X yWE/yVE + yWO 
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The following list describes the variables used in these transformation 


equations: 
Variable 


xWO 
yWO 


Dy 


Description 


Window origin 2-coordinate 

Window origin y coordinate 

Window extent 2-coordinate 

Window extent coordinate 

Viewport origin 2-coordinate 

Viewport origin coordinate 

Viewport extent 2-coordinate 

Viewport extent ycoordinate 
Logical-coordinate system 2z-coordinate 
Logical-coordinate system ycoordinate 
Device 2-coordinate 


Device y-coordinate 


The following four ratios are scaling factors: 


x VE/xWE 
y VE/yWE 
xWE/xVE 
y WE/yVE 


They are used to determine the necessary stretching or compressing of log- 
ical units. The subtraction and addition of viewport and window origins 1s 
referred to as the translational component of the equation. 
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2.3.4.4 Example: MM_ TEXT 


The default mapping mode is MM_ TEXT. In this mapping mode, one logi- 
cal unit is mapped to one pixel on the device or display. 


A simple Windows application created three rectangles as they appear in 
the logical and physical coordinate spaces when MM_ TEXT is the map- 
ping mode, as shown in Figure 2.9. The drawing on the left illustrates the 
logical space; the drawing on the right illustrates the device, or physical, 
space. The rectangles appear vertically elongated in the physical space 
because pixels on the chosen display are longer than they are wide. The 
rectangles appear to be upside-down because positive y extends downward 
in the physical-coordinate system: 


y-axls origin 
(+)? 


* y-axis 
+) 


deere cee= 72 e=e 
(-) 
(-), y-axis | 
Logical Coordinate System Physical Coordinate Systen 


Figure 2.9 Mapping with MM_ TEXT 


2.3.4.5 Example: MM_LOENGLISH 


A Windows application created three rectangles and mapped them from 
the logical space to the physical space by using the MM. LOENGLISH 
mapping mode, as shown in Figure 2.10. The drawing on the left illus- 
trates how the rectangles appear in relation to the a and yaxes in the 
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logical coordinate system. The drawing on the right illustrates how the 
rectangles appear in relation to the a and yaxes in the physical coor- 
dinate system: 


y-axis y-axis 
(+) 4 


+4 
Wi 
daeeneee- ¢----- mm-b MAXLS ¢--------- 7 olin ~------- * X-axis 
(-) ' origin (+) (-) | origin (+) 
a t 
(=): (4)? 
Logical Coordinate Systen Physical Coordinate Systen 


Figure 2.10 Mapping with MM. LOENGLISH 


2.3.5 Coordinate Functions 


Coordinate functions convert client coordinates to screen coordinates (or 
vice versa), and determine the location of a specific point. These functions 
are useful in graphic-intensive applications. The following list briefly 
describes each coordinate function: 


Function Description 
ChildWindowFromPoint Determines which child window 


contains a specified point. 


Client ToScreen Converts chent coordinates into 
screen coordinates. 


Screen ToClient Converts screen coordinates into 
client coordinates. 


WindowFromPoint Determines which window contains a 
specified point. 


106 


2.3.6 Region Functions 


Functions Overview 


Region functions create, alter, and retrieve information about regions. A 
region is an elliptical or polygonal area within a window that can be filled 
with graphical output. An application uses these functions in conjunction 
with the clipping functions to create clipping regions. For more informa- 
tion about clipping functions, see Section 2.3.7. The following list briefly 


describes each region function: 


Function 


CombineRgn 


CreateEllipticRgn 
CreateEllipticRgnIndirect 
CreatePolygonRgn 
CreateRectRgn 
CreateRectRgnIndirect 
EqualRgn 


FillRgn 


FrameRgn 
InvertRgn 
OffsetRgn 


PaintRgn 
PtInRegion 


SetRectRgn 


Description 

Combines two existing regions into 
a new region. 

Creates an elliptical region. 
Creates an elliptical region. 
Creates a polygonal region. 
Creates a rectangular region. 
Creates a rectangular region. 


Determines whether two regions are 
identical. 


Fills the given region with a brush © 
pattern. 


Draws a border for a given region. 
Inverts the colors in a region. 
Moves the given region. 


Fills the region with the selected 
brush pattern. 


Tests whether a point is within a 
region. 


Creates a rectangular region. 
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2.3.7 Clipping Functions 


Clipping functions create, test, and alter clipping regions. A clipping 
region is the portion of a window’s client area where GDI creates output; 
any output sent to that portion of the client area which is outside the clip- 
ping region will not be visible. Clipping regions are useful in any Windows 
application that needs to save one part of the client area and simultan- 
eously send output to another. The following list briefly describes each 
clipping function: 


Function Description 

ExcludeClipRect Excludes a rectangle from the clipping region. 

GetClipBox Copies the dimensions of a bounding rectangle. 

IntersectClipRect Forms the intersection of a clipping region and 
a rectangle. 

OffsetClipRgn Moves a clipping region. 

PtVisible Tests whether a point lies in a region. 

Rect Visible Determines whether part of a rectangle lies in 
region. 

SelectClipRgn Selects a clipping region. 


2.3.8 Line-Output Functions 


Line-output functions create simple and complex line output with the 
selected pen. The following list briefly describes each line-output function: | 


Function Description 

Arc Draws an arc. 

LineDDA Computes successive points on a line. 

LineTo Draws a line with the selected pen. 

MoveTo Moves the current position to the specified 
point. 

Polyline Draws a set of line segments. 
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2.3.8.1 Function Coordinates 


Line-output functions require coordinates in logical units, which GDI uses 
to draw a line in logical space. The use of logical units ensures device 
independence in Windows. GDI maps this line from the logical space to the 
physical space on the device. The number of logical units that GDI maps 
to a pixel depends on the current mapping mode. When GDI draws a line, 
it excludes the last specified point. For example, if the LineTo function is 
given the arguments X1, Yi and X2, Y2, the line will be drawn from X7, 
Y1 to X2—1, Y2—1. 


2.3.8.2 Pen Styles, Colors, Widths 


If an application draws lines and does not create a new pen, GDI uses the 
default pen. This pen is black and is one pixel wide when the mapping 
mode is MM_ TEXT. An application can create a new pen of a different 
width, style, and color by using the CreatePen function. The new color is 
dependent on the color capabilities of the output device. The new style can 
be solid, dotted, dashed, or a combination of dotted and dashed. Once an 
application creates a new pen, it can select it into a display context by 
using the SelectObject function. 


Figure 2.11 shows simple line output created by the LineTo and MoveTo 
functions. The application created the rectangle on the left by using a 
styled pen and the rectangle on the right by using a solid pen: 


Figure 2.11 Styled- and Solid-Pen Rectangles 
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Figure 2.12 shows complex line output created by the Polyline function. 
The application created the box on the left by using a styled pen and the 
box on the right by using a solid pen: 


es ae 
ry boy 
oy _ 
aa PS 


Figure 2.12 Styled- and Solid-Pen Boxes 


Figure 2.13 shows an arc created by using the Arc function. The upper 
portion of the illustration shows the arc as it would appear on a display; 
the lower portion shows the arc suspended in its bounding rectangle, 
which GDI uses to determine the size and shape of the arc: 


Figure 2.13 Arce 


2.3.9 Ellipse and Polygon Functions 


Ellipse and polygon functions draw ellipses and polygons. GDI draws the 
perimeter of each object with the selected pen and fills the interior by 
using the selected brush. These functions are particularly useful in draw- 
ing and charting applications. The following list briefly describes each 
ellipse and polygon function: 


Function Description 

Chord Draws a chord. 

Ellipse Draws an ellipse. 

Pie Draws a ple. 

Polygon Draws a polygon. 
Rectangle Draws a rectangle. 
RoundRect Draws a rounded rectangle. 
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2.3.9.1 Function Coordinates 


Ellipse and polygon functions require coordinates in logical units, which 
GDI uses to determine the location and size of an object in logical space. 
The use of logical units ensures device independence in Windows. GDI uses 
a mapping function to map logical units to pixels on the device. The num- 
ber of logical units that Windows maps to a pixel depends on the current — 
mapping mode. The default mapping mode, MM_ TEXT, maps one logical 
unit to one pixel. | 


When GDI draws a rectangle, it uses four arguments. The first two argu- 
ments specify the rectangle’s upper-left corner. The last two arguments do 
not actually specify part of the rectangle; they specify the point adjacent 
to the lower-right corner. For example, if the first point is specified by XJ, 
Y1 and the second point is specified by X2, Y2, the rectangle’s upper-left 
corner will be XJ, Y1 and the lower-right corner will be X2— 1, Y2— 1. 


2.3.9.2 Bounding Rectangles 


Instead of requiring a radius or circumference measurement, the Chord, 
Ellipse, and Pie functions use a bounding rectangle to define the size of 
the object they create. The bounding rectangle is hidden; GDI uses it only 
to describe the object’s location and size. 


For information about functions that alter or obtain information about 
rectangles in a window’s client area, see Section 2.2.18. 


2.3.10 Bitmap Functions 


Bitmap functions display bitmaps. A bitmap is a matrix of memory bits 
that, when copied to a device, defines the color and pattern of a corre- 
sponding matrix of pixels on the device’s display surface. Bitmaps are use- 
ful in drawing, charting, and word-processing applications because they let 
you prepare images in memory and then quickly copy them to the display. 
The following list briefly describes each bitmap function: _ 
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Function 


BitBlt 


CreateBitmap 
CreateBitmapIndirect 


CreateCompatibleBitmap 


FloodFill 
GetBitmapBits 


GetBitmapDimension 
GetPixel 
LoadBitmap 

PatBlit 
SetBitmapBits 
SetBitmapDimension 
SetPixel 

StretchBlt 
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Description 

Copies a bitmap from a source to a 
destination device. 

Creates a bitmap. 


Creates a bitmap described in a data 
structure. 


Creates a bitmap that is compatible 
with a specified device. 


Fills the display surface. 


Retrieves the bits in memory for a 
specific bitmap. 


Retrieves the dimension of a bitmap. 
Retrieves the RGB value for a pixel. 
Loads a bitmap from a resource file. 
Creates a bit pattern. 

Sets the bits of a bitmap. 

Sets the height and width of a bitmap. 
Sets the RGB value for a pixel. 


Copies a bitmap from a source to a 
destination device (compresses or 
stretches, if necessary). 


Functions Overview 


2.3.10.1 Bitmaps and Devices 


The relationship between bitmap bits in memory and pixels on a device is 
device-dependent. On a monochrome device, the correspondence is usually 
one-to-one, where one bit in memory corresponds to one pixel on the 
device. 


2.0.11 Text Functions 


Text functions retrieve text information, alter text alignment, alter text 
justification, and write text on a device or display surface. GDI uses the 
current font for text output. The following list briefly describes each text 
function: 


Function Description 

Get TextAlign Returns a mask of the text alignment flags. 

GetTextExtent Uses the current font to compute the width and 
height of text. 

Get TextFace Copies the current font name to a buffer. 

Get TextMetrics Fills the buffer with metrics for the selected font. 

Set TextAlign Positions a string of text on a display or device. 

SetTextJustification Justifies a text line. 

TextOut Writes a character string using the current font. 


2.3.12 Font Functions 


Font functions select, create, remove, and retrieve information about 
fonts. A font is a subset of a particular typeface, which is a set of charac- 
ters that share a similar fundamental design. 
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The following list briefly describes each font function: 


Function Description 

AddFontResource Adds a font resource in the specified file 
to the system font table. 

CreateF ont Creates a logical font that has the 
specified characteristics. 

CreateF ontIndirect Creates a logical font that has the 
specified characteristics. 

EnumFonts Enumerates the fonts available on a given 
device. 

GetChar Width Retrieves the widths of individual 
characters. 

RemoveF ontResource Removes a font resource from the font 
table. 

SetMapperF lags Alters the algorithm the font mapper 
uses. 


A font family is a group of typefaces that have similar stroke-width and 
serif characteristics. A typeface is a set of characters (letters, numerals, 
punctuation marks, symbols) that share a common design. Font characters 
share very specific characteristics, such as point size and weight. 


Note that the terms GDI uses to describe fonts, typefaces, and families of 
fonts do not necessarily correspond to traditional typographic terms. 


The Helvetica typeface is an example of a familiar typeface. It belongs to 
the Swiss font family. Available fonts within this typeface include 8-point 
Helvetica bold and 10-point Helvetica italic. 


Figure 2.14 shows several fonts from the Helvetica and Courier typefaces: 


This is & line of 12 point Helvetica. 


This is a line of 12 point Helvetica bold. 
This is @ ling of 12 point Helvetica iake 


This is a line of 12 point Courier. 
This is a line of 12 point Courier bold. 
This if a ling of Ll? point Courler italic. 


Figure 2.14 Fonts from Two Typefaces 
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2.3.12.1 Font Family 


GDI organizes fonts by family; each family consists of typefaces and fonts 
that share a common design. The families are divided by stroke width and 
serif characteristics. The term stroke, which means a horizontal or vertical 
line, comes from handwritten characters composed of one or more pen 
strokes. The horizontal stroke is called a cross-stroke. The main vertical 
line is called a stem. Figure 2.15 shows a lowercase f composed of a cross- 
stroke and a stem with a loop at the top: 


cross-stroke 


Sten 


Figure 2.15 Cross-Stroke and Stem 


Serifs are short cross-lines drawn at the ends of the main strokes of a 
letter. If a typeface does not have serifs, it is generally called a sans-serif 
(without serif) typeface. Figure 2.16 shows serifs: 


serif 
serif fi \ L, serif 


Figure 2.16 Serifs 


GDI uses five distinct family names to categorize typefaces and fonts. A 
sixth name is used for generic cases. Note that GDI’s family names do not 
correspond to traditional typographic categories. Table 2.12 lists the 
font-family names and briefly describes each family: 
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Table 2.12 


Font Families 
Name Description 


Dontcare Generic family name. Used when information about a 
font does not exist or does not matter. 


Decorative Novelty fonts. Old English, for example. 


Modern Constant stroke width (fixed-pitch), with or without 
serifs. Fixed-pitch fonts are usually modern. Pica, Elite, 
and Courier, for example. 


Roman Variable stroke width (proportionally spaced), with 
serifs. Times Roman, Palatino, and Century Schoolbook, 
for example. 


Script Designed to look like handwriting. Script and Cursive, 
for example. 
Swiss Variable stroke width (proportionally spaced), without 


serifs. Helvetica and Swiss, for example. 


2.3.12.2 Character Cells 


A character is the basic element in a font. In GDI, each character is con- 
tained within a rectangular region known as a character cell. This rect- 
angular region consists of a specific number of rows and columns, and 
possesses S1x points of measurement: ascent, baseline, descent, height, 
origin, and width. The following list describes these measurements: 


Measurement Description 

Ascent Specifies the distance in character-cell rows from 
the character-cell baseline to the top of the char- 
acter cell. 

Baseline Serves as the base on which all characters stand 


(some lowercase letters have descenders, such 
as the tail of the gor y, that descend below the 
baseline). 


Descent Specifies the distance in character-cell rows from 
the character-cell baseline to the bottom of the 
character cell. 
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Height Specifies the height of a character-cell row. 


Origin Used as a point of reference when the character is 
written on a device or a display surface. The ori- 
gin is the upper-left corner of the character cell. 


Width Specifies the width of a character-cell column. 


Figure 2.17 shows a character cell that contains an uppercase A. The 
baseline appears at the top of the second row. Note that the uppercase 
A uses the baseline as its starting point. Also note that the width and 
height values refer to the character-cell width and height, not the width 
and height of the individual character: 


origin 
ascent | 
height 


descent + 
width| * 


Figure 2.17 Character-Cell Dimensions 


2.3.12.3 Characters 


Characters exist In many sizes and shapes. Sections 2.3.12.4 through 
2.3.12.7 describe how characters are altered in GDI to produce a particular 
font. 


2.3.12.4 Italic 


For an italic font, GDI skews the characters so that they appear slanted. 
When italicized, the base of the character remains intact while the upper 
portion shifts to the right. The greatest amount of shifting occurs at the 
top of the character, the least amount at the base. Figure 2.18 shows char- 
acters before and after being italicized: 
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AlallAla 


This font is tlalicized. fhe base of 
each character remalas rtntacl while 
the upper portion is skewed ta the 
right. 


Figure 2.18 Normal and Italic Characters 


2.3.12.5 Bold 
A font is made bold by increasing its weight, which refers to the thick- 


ness of the lines or strokes that compose a character. Fonts with a heavy 
weight are referred to as bold. Figure 2.19 shows normal and bold 


AlajAla 


These two sentences illustrate the 
result of varying font weight. & 
heavier weight gives you a 
bolder foat. 


Figure 2.19 Normal and Bold Characters 
2.3.12.6 Underline 
An underline font has a line under each character. When a character is 


underlined, a solid line appears directly below the baseline of the character 
cell. Figure 2.20 shows underlined characters: 
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Ala 


r 


of each character cell. 
Figure 2.20 Underlined Characters 


2.3.12.7 Strikeout 


A strikeout font has a solid horizontal line drawn through each character. 
The position of this line within each character cell is constant for a given 
font. Figure 2.21 shows characters that are struck out: 


Ae 


ateribute, 


Figure 2.21 Struckout Characters 


2.3.12.8 Leading 


Leading is the distance from baseline to baseline of two adjacent rows of 
text. When font designers develop a font, they specify that a given amount 
of space should appear between rows. The addition of this space ensures 
that a character is not obscured by part of another character in an 
adjacent row. There are two ways of adding this additional space: 

by inserting it within the character cells of a font (internal leading) 

or by inserting it between rows of text as they are printed on a device 
(external leading). 
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Internal Leading 


Internal leading refers to the space inserted within character cells of a par- 
ticular font. Only marks such as accents, umlauts, and tildes in foreign 
character sets appear within the space allocated for internal leading. 
Figure 2.22 shows two rows of text that use internal leading: 


Top of character 
ul. rae 
Character—cell 
Internal . 
leading baseline 


Leading 


ea 


Bottom of hacelina 


character cell 
Figure 2.22 Internal Leading 


External Leading 

External leading is space inserted between the top and bottom of charac- 
ter cells in adjacent rows of text. The font designer must specify the 
amount of external leading necessary to produce easily readable text from 


a particular font. External leading is not built into a font; you must add it 
before you print text on a device. Figure 2.23 shows external leading: 


Thal 


an om 


Figure 2.23 External Leading 
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2.3.12.9 Character Set 


All fonts use a character set. A character set contains punctuation marks, 
numerals, upper- and lowercase letters, and all other printable characters. 
The designer of a character set assigns a numeric value to each element in 
the set. You use this number to access an element within the set. 


ANSI Character Set 


The ANSI character set, shown in Figure 2.24, is the most commonly used 
character set. The blank character is the first character in the ANSI char- 
acter set. It has a hexadecimal value of 20, which is equivalent to the 
decimal value 32. The last character in the ANSI character set has a hexa- 
decimal value of FF, which is equivalent to the decimal value 255. 


Many fonts specify a default character. Whenever a request is made for a 
character not in the set, this default character is given. Most fonts using 
the ANSI character set specify the period (.) as the default character. The 
hexadecimal value for the period is 2E, or decimal 46 in the ANSI char- 
acter set. 


Fonts use a break character to separate words and justify text. Most fonts 
using the ANSI character set specify the blank character, whose hexadec- 
imal value is 20, decimal 32. 


Figure 2.24 shows the ANSI character set: 


ANSI Character Set 
GQ G1 G2 & 


m ~* 
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Figure 2.24 ANSI Character Set 
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OEM Character Sets 


Some devices contain characters that are not part of the ANSI character 
set. The device manufacturer usually provides a character set, called an 
OEM character set, when this occurs. The first 128 characters in an OKM 
character set are sometimes identical to the first 128 characters in the 
ANSI character set. The remaining characters in the OEM character set 
correspond to the characters on the manufacturer’s device that are not 
included in the ANSI character set. 


2.3.12.10 Pitch 


The term pitch traditionally refers to the number of characters from a 
particular font that will fit in a single inch. GDI, however, uses this term 
differently. The term fixed-pitch refers to a font whose character-cell size 
is constant for each character. The term variable-pitch refers to a font 
whose character cells vary in size, depending on the actual width of the 
characters. 


2.3.12.11 Average Character Width 


Variable-pitch fonts use the average character width to specify the aver- 
age width of character cells in the font. Since there is no variance in 
character-cell width for fixed-pitch fonts, the average character width 
specifies the character width of any character in the fixed-pitch font. 


2.3.12.12 Maximum Character Width 


Variable-pitch fonts use the maximum character width to specify the max- 
imum width of any character cell in the font. Since there is no variance in 
character width for fixed-pitch fonts, the maximum character width is 
equivalent to the average character width in the fixed-pitch font. 


2.3.12.13 Digitized Aspect 


When raster fonts are created, they are designed with one particular 
aspect ratio in mind. The aspect ratio is the ratio of the width and height 
of a device’s pixel. GDI maintains a record of the ideal aaspect and 
y-aspect for individual fonts. The ideal s-aspect is the width value from 
the aspect ratio of the device. The ideal yaspect is the height value 

from the aspect ratio of the device. These values are called the digitized 
aspect for zand y. 
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2.3.12.14 Overhang 


When a particular font is not available on a device, GDI sometimes syn- 
thesizes that font. The process of synthesizing may add width or height to 
an existing font. Whenever GDI synthesizes an italic or bold font from a 
normal font, extra columns are added to individual character cells in that 
font. The difference in width (the extra columns) between a string created 
with the normal font and a string created with the synthesized font is 
called the overhang. 


2.3.12.15 Selecting Fonts with GDI 


GDI maintains a collection of fonts from different typefaces. In addition 
to this collection, some devices maintain a collection of hardware fonts 
in their ROM. GDI lets you describe a font and then selects the closest 
matching available font from your description. 


GDI requires you to describe the font you want to use to create text. The 
font you describe is a logical font (it may or may not actually exist). GDI 
compares this logical font to the available physical fonts and selects the 
closest match. 


The process of selecting the physical font that bears the closest resem- 
blance to the specified logical font is known as font mapping. GDI also 
maintains a font table. Each entry in the font table describes a physical 
font and its attributes. Included in each entry is a pointer to a correspond- 
eo resource. Figure 2.25 shows a font table that contains fonts X, Y, 
and Z: 


FONT TABLE 


} Front & Information | 
| Leading|italic/underline [weight 
[char set {width| height! 

esdrea Pane Information 
ese : 


reder Teas Ta 


Ea eee a 
char se 
[patch and family 


Pointer to 
font X resource 


Pointer to 
Font ¥ resource 


Pointer to 
font Z resource 


Figure 2.25 GDI’s Font Table 
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2.3.12.16 Font-Mapping Scheme 


The GDI font mapper assigns penalties to physical fonts whose charac- 
teristics do not match the characteristics of the specified logical font. 
The physical font with the fewest penalties assigned is the one that GDI 
selects. | 


Table 2.13 lists the characteristics that are penalized by GDI’s font 
mapper. The characteristics are grouped according to penalty weights, 
with the heaviest penalty assigned to the CharSet characteristics and the 
lightest penalty assigned to the Weight, Slant, Underline, and StrikeOut 
characteristics. 


Table 2.13 
Font-Mapping Characteristics 


Characteristic Penalty Scheme Penalty Weight 


CharSets If the character sets do not 4 
match, the candidate font is 
penalized heavily. 


Pitch If a variable-pitch font is 3 
requested, a candidate font 
with fixed pitch is penalized 
heavily (and vice versa). 


~ Family If the font families do not 3 
match, the candidate font is 
penalized heavily. If a default 
font family is requested, no 
penalties are assessed. 


FaceName If the font typeface names do 3 
not match, the candidate font 
is penalized heavily. 


Height If the candidate font height is 2 
less than the requested font | 
height, GDI will multiply (by 
up to eight) the candidate 
height to produce a match. A 
penalty is assessed for this 
stretching and for any 
remaining height differences. 
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Table 2.13 (continued) 


Characteristic Penalty Scheme Penalty Weight 
Width Differences in width are 2 

treated much like differences 

in height. 
Weight If the requested font weight 1 


is not equal to that of the 
candidate font, GDI penalizes 
the candidate. 
Slant If the requested font is 1 
italicized but the candidate 
font is not {or vice i) GDI 
penalizes the candidate font. 
Underline If the requested font is 1 
underlined but the candidate 
font is not (or vice picker GDI 
penalizes the candidate font. 
StrikeOut If the requested font is struck 1 
out but the candidate font is 
not (or vice versa), GDI 
penalizes the candidate font. 


2.3.12.17 Example of Font Selection 


For the purpose of this example, assume that the system font table lists 
only the three fonts shown in Figure 2.25, fonts X, Y, and Z. Suppose 

you need to use a specific font, font Q, to create text on an output device. 
You will need to describe font Q so that GDI can choose the physical font 
(X, Y, or Z) that bears the closest resemblance to Q, 


To describe font Q, you use the CreateFont or CreateFontIndirect 
GDI function. These functions create a logical font which is a description 
of the desired physical font. 


Use the SelectObject function to select the physical font that most 
closely matches logical font Q. (The SelectObject function requires that 
you pass a handle to font Q.) Once a call to the SelectObject function 
occurs, GDI will initiate the selection process. 


Table 2.14 shows the physical fonts in the font table and the penalties 
that GDI assigns to each as it tries to find a font that will match font Q. 
The left column shows the font attributes that GDI compares; the second 
column gives the attributes of font Q, the desired font. The attributes of 
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fonts X, Y, and Z—the fonts that are actually in the system font table— 
are followed by the penalty values that GDI gives to each one. The bottom 
row of the table gives the penalty totals for each font: 


Table 2.14 
Sample Font Selection Ratings 


Desired Available Fonts/Penalty Score 
x Y Z 


Attributes 

CharSet ANSI OEM 4 OEM 4 ANSI 0 
Pitch Fixed Variable 3 Fixed 0 Variable 3 
Family Roman Modern 3 Roman QO Modern 3 
FaceName TmsRmn Pica 3 TmsRmn 0 _ Elite 3 
Height 8 10 2 10 2 8 0 
Width 4 6 2 6 2 4 0 
Slant None None 0 None 0 None 0 
Underline None None 0 None 0 None 0 
StrikeOut None None 0 None 0 None 0 
Penalty Total 17 8 9 


The penalty totals show that font Y has the lowest penalty score and 
therefore resembles font Q most closely. In this example, GDI would select 
font Y as the physical font on the output device. 


2.3.12.18 Font Files and Font Resources 


GDI stores information about the physical font in font files. The font file 
consists of a header and a bitmap. The font-file header contains a detailed 
description of the font. If the font file is a raster file, the font-file bitmap 
contains actual representations of the font characters. If the font file 

is a vector file, the font-file bitmap contains character strokes for the 

font characters. A font resource is a collection of one or more of these 
physical-font files. 
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2.3.13 Metafile Functions 


Metafile functions close, copy, create, delete, retrieve, play, and return 
information about metafiles. A metafile is a collection of GDI commands 
that creates desired text or images. The following list briefly describes 
each metafile function: 


Function Description 

CloseMetaFile Closes a metafile and creates a metafile 
handle. 

CopyMetaF ile Copies a source metafile to a file. 

CreateMetaF ile Creates a metafile display context. 

DeleteMetaF ile Deletes access to a metafile. 

Enum MetaFile Enumerates the GDI calls within a metafile. 

GetMetaF ile Creates a handle to a metafile. 

GetMetaFileBits Stores a metafile as a collection of bits in a 
global memory block. 

PlayMetaF ile Plays the contents of a specified metafile. 

PlayMetaF ileRecord Plays a metafile record. 

Set MetaFileBits Creates a memory metafile. 


2.3.13.1 Using a Metafile 


Metafiles provide a convenient method of storing graphic commands that 
create text or images. Metafiles are especially useful in applications that 
use specific text or a particular image repeatedly. They are also device- 
independent; by creating text or images with GDI commands and then 
placing the commands in a metafile, an application can re-create the text 
or images repeatedly on a variety of devices. Metafiles are also useful in | 
applications that need to pass graphic information to other applications. 


2.3.13.2 Creating a Metafile 


A Windows application must create a metafile in a special device con- 
text. It cannot use the device concepts that the CreateDC or GetDC 
functions return; instead, it must use the device context that the 
CreateMetaF ile function returns. 


127 


Microsoft Windows Programmer’s Reference 


Windows allows an application to use a subset of the GDI functions to 
create a metafile. This subset is the set of all GDI functions that create 
output (it is not necessary to use those functions that provide state infor- 
mation, such as the GetDeviceCaps or GetEnvironment functions). 
The following list provides a list of GDI functions an application can use 
in a metafile: 


Arc PaintRgn SetPixel 

Bit Blt PatBlt SetPolyFillMode 
Chord Pie SetRelAbs 

Ellipse Polygon SetROP2 

Escape Polyline SetStretchBltMode 
ExcludeClipRect Rectangle Set TextCharExtra 
FillRgen RestoreDC Set TextColor 
FloodF ill RoundRect Set Text Justification 
FrameRgn SaveDC Set ViewportExt 
IntersectClipRect Scale ViewportExt Set View portOrg 
InvertRgn ScaleWindowExt Set WindowExt 
LineTo SelectClipRgn Set WindowOrg 
MoveTo SelectObject StretchBit 

Offset ClipRect SetBkColor TextOut 


- OffsetViewportOrg SetBkMode 
Offset WindowOrg SetMapMode 


To create output with a metafile, an application must follow three steps: 
1. Create a special device context by using the CreateMetaF ile 


function. 


2. Send GDI commands to the metafile by using the special device 
context. 


3. Display the image or text on a device by using the PlayMetaFile 
function. 


After the application creates output with a metafile, it should close the 
metafile by using the CloseMetaFile function. 
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2.3.13.3 Example: Metafile Output 


Figure 2.26 shows a cube and its exploded view. These illustrations were 
created by using metafile functions: 


Figure 2.26 Cube and Exploded Cube 
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2.3.14 Printer-Escape Functions 


Printer-escape functions regulate the flow of printer output from Windows 
applications, retrieve information about a printer, and alter the settings of 
a printer. The following list briefly describes each printer-escape function: 


Function Description 

ABORTDOC Terminates the current job. 

DEVICEDATA Allows the application to send data 
directly to the printer. 

DRAFTMODE Turns draft mode on or off. 


ENABLEPAIRKERNING — Enables or disables the driver’s ability to 
kern character pairs. 


ENABLERELATIVEWIDTHS 
Enables or disables relative character 
widths. 

ENDDOC Ends a print job started by the START- 
DOC function. 

, T Provides a more efficient way for the 

ication to call the GDI TextOut 

function. 

FLUSHOUTPUT Flushes output in the device buffer. 

GETCOLORTABLE a an RGB color-table entry to a 
buffer. 


GETEXTENDEDTEXTMETRICS 
Fills a buffer with the extended text 
metrics. 


GETEXTENTTABLE Returns the width of individual characters 


from a font’s character set. 


GETPHYSPAGESIZE Copies the physical page size to a data 
structure. 


GETPRINTINGOFFSET Copies the printing offset to a data 


structure. 
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GETSCALINGFACTOR — Copies scaling factors to a data structure. 


GETTRACKKERNTABLE 
Fills a buffer with the track-kerning table 
for a selected font. 


MF COMMENT Adds a comment to a metafile. 


NEWFRAME Ends writing to a page. 
NEXTBAND Ends writing to a band. 


QUERYESCSUPPORT Tests whether an escape is supported by a 
device driver. 


SELECTPAPERSOURCE Determines the available paper sources 
and selects one. 


SETABORTPROC Sets the abort function for a print job. 

SETCOLORTABLE Sets an RGB color-table entry. 

SETCOPYCOUNT Specifies the number of uncollated copies 
of each page to be printed. 

SETKERNTRACK Specifies which kerning track will be used. 

STARTDOC Starts a print job. 

STRETCHBLT Implements the GDI StretchBlt function 


on the driver level. 


2.3.14.1 Creating Output 


Windows applications use only the standard Windows functions to access 
system memory, the output device, the keyboard, and the mouse. Each 
application interacts with the user through one or more windows that are 
created and maintained by the user. GDI assists an application in creating 
output by passing device-independent function calls from the application 
to the device driver. The device driver first translates these device- 
independent function calls into device-dependent operations that create 
images on a device’s display surface, and then sends them to the spooler. 
The spooler serves two purposes: it collects translated commands from 
one application and stores them in a corresponding job, and it passes a 
complete job to the device for output. Figure 2.27 shows the path of out- 
put from a Windows application to a device: 
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— Output device 


Figure 2.27 Output Path 


If only one Windows application were allowed to run at any given time, 
the spooler and many of the escape functions would be unnecessary. How- 
ever, Windows allows several applications to run at once. If two or more of 
these applications send output simultaneously, each application’s output 
must be separated and remain separated during printing or plotting. The 
spooler maintains this separation. The printer-escape functions affect the 
way the spooler handles this separation task. 


2.3.14.2 Banding 


The model used by GDI states that any point on an output device can be 
written to at any time. This model is easily implemented on vector devices 
but poses a problem on many dot-matrix devices that cannot scroll back- 
ward. Banding provides a solution to this problem. 


Banding involves several steps: 
1. The application creates a metafile and uses it as an intermediate 
storage device for the output. 


2. Beginning at the top of the metafile, GDI translates a rectangular 
region (band) of output into device-specific commands, and then 
sends it to a corresponding job. 


3. The application repeats this process until the entire metafile has 
been converted to bands and the output from these bands has been 
translated into device-specific commands and stored in a Job. 


4. The application sends the job to the output device. 
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When creating a device context, GDI verifies whether the device has band- 
ing capabilities. If it does, GDI creates the metafile that will be used dur- 
ing the banding process. T’o implement banding, you call the necessary 
output functions and the NEXTBAND escape. The NEXTBAND 
escape requires a long pointer toa RECT data structure as its output 
parameter. The device driver copies the coordinates of the next band into 
this structure. When the entire metafile has been converted into device- 
specific commands, the driver returns four zeros (0,0,0,0) in the RECT 
structure. 


GDI does the banding for you if your output device has banding capabili- 
ties and you call the NEWFRAME escape. Although NEWFRAME 
requires more memory, it does simplify the output process. After the appli- 
cation creates each page of output, it calls the NEWFRAME escape. If 
the device is capable of banding, GDI copies output to a metafile and calls 
the NEXTBAND escape for you. As discussed earlier, the NEXTBAND 
escape causes the contents of the metafile to be converted into device- 
specific commands and to be copied to a corresponding job. If a memory 
problem occurs or the user terminates a Job, the NEWFRAME escape 
returns a message that defines the error or abort message. 


2.3.14.3 Starting and Ending a Print Job 


The STARTDOC escape informs the device driver that an application is 
beginning a new print job. After the STARTDOC call is issued, the 
spooler queues all output from a particular application in a corresponding 
job until an ENDDOC escape is issued. (Note that you cannot use the 
ENDDOC escape to terminate a job.) 


2.3.14.4 Terminating a Print Job 


If you send output to a device with the NEWFRAME escape, you are 
required to write a termination procedure and supply it with the applica- 
tion. The SETABORTPROC escape sets a pointer to this procedure; it 
should be called prior to the STARTDOC escape. The ABORTDOC 
escape terminates print jobs if it is called before the first call to NEW- 
F . It should also be used to terminate jobs that use the 
NEXTBAND escape. 
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2.3.14.5 Information Escapes 


Four of the escape functions are used to retrieve information about the 
selected device and its settings. The GETPHYSPAGESIZE escape 
retrieves the physical page size of the output device (in device units), 
the smallest addressable units on the device. For example, one-fortieth 
of a millimeter is the smallest addressable unit on some vector devices. 
A pixel is the smallest addressable unit on a dot-matrix device. The 
GETPRINTINGOFFSET escape retrieves the distance (in device 
units) from the upper-left corner of the page to the point at which print- 
ing begins. The GETSCALINGFACTOR escape retrieves the scaling 
factors for the » and yaxes of a device. The scaling factor expresses 

the number of logical units that are mapped to a device unit. The 
QUERYESCSUPPORT escape determines whether a particular escape 
function is implemented on a device driver. If the escape in question is 
implemented, QUERYESCSUPPORT returns a nonzero value. If the 
escape is not implemented, QUERYESCSUPPORT returns zero. 


2.3.14.6 Additional Escape Calls 


There are two additional escapes that alter the state of the device: the 
FLUSHOUTPUT and DRAFTMODE escapes. The FLUSH- 
OUTPUT escape flushes the output in the device’s buffer (the device 
stores device operations in the buffer before sending them to the spooler). 
The DRAFTMODE escape turns on the device’s draft mode. This means 
that the device will use one of its own fonts instead of using a GDI font. 

It also means that calls to the text-justification functions that alter 
interword and intercharacter spacing are ignored. For a detailed descrip- 
tion of the functions that alter interword and intercharacter spacing, 

see Sections 2.3.11 and 2.3.12. 


2.3.15 Environment Functions 
Environment functions alter and retrieve information about the environ- 


ment associated with an output device. The following list briefly describes 
the two enviornment functions: 


Function Description 
GetEnvironment Copies environment information into a buffer. 
SetEnvironment Copies data to the environment associated with - 


an attached device. 
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2.4 System Services Interface 
Function Groups 


The system services interface contains the functions that access code and 
data in modules, allocate and manage both local and global memory, 
manage tasks, load program resources, translate strings from one char- 
acter set to another, alter the Windows initialization file, assist in sys- 
tem debugging, carry out communications through the system’s I/O 
ports, create and open files, and create sounds using the system’s sound 


generator. 


2.4.1 Module-Manager Functions 


Module-manager functions alter and retrieve information about Windows 
modules, loadable, executable units of code and data. The following list 
briefly describes each module-manager function: 


Function 


FreeLibrary 
FreeProcInstance 
GetInstanceData 


GetModuleF ileName 
GetModuleHandle 
GetModuleUsage 
GetProcAddress 


Get Version 


LoadLibrary 


MakeProclInstance 


Description 
Removes a library module from memory if 
the lock count is zero. 


Removes a function instance entry at an 
address. 


Copies data from an offset in one instance 
to an offset in another instance. 


Copies a module filename. 
Returns the module handle of a module. 
Returns the reference count of a module. 


Returns the address of a function in a 
module. 


Returns the current version number of 
Windows. 


Loads a library module. 


Returns a function-instance address. 
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2.4.2 Memory-Manager Functions 


Memory-manager functions manage system memory. There are two 
categories of functions: global-memory-manager functions and local- 
memory-manager functions. Global memory is all memory in the system 
that has not been allocated by an application or reserved by the system. 
Local memory is the memory within a Windows application’s data seg- 
ment. The following list briefly describes each memory-manager function: 


Function 


GlobalAlloc 


GlobalCompact 


GlobalDiscard 
GlobalF lags 


GlobalFree 
GlobalLock 


GlobalReAlloc 
GlobalSize 


GlobalUnlock 


GlobalUnwire 
GlobalWire 


LocalAlloc 
LocalCompact 


LocalDiscard 


LocalF lags 
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Description 


Allocates memory from the global heap. 


Compacts global memory to generate free 
bytes. 


Discards a global memory block if the lock 
count is zero. 


Returns the flags and lock count of a global 
memory block. 


Removes a global memory block. 


Locks a block in memory by increasing the 
lock count. 


Reallocates a global memory block. 


Returns the size (in bytes) of a global 
memory block. 


Decreases the lock count and unlocks the 
memory block if the count is zero. 


Sets the lock count to zero. 


Moves an object to low memory and 
increases the lock count. 


Allocates memory from the local heap. 
Compacts local memory. 


Discards a local memory block if the lock 
count is zero, 


Returns the memory type of a local memory 
block. 


LocalF ree 


LocalFreeze 
LocalHandleDelta 


LocalLock 


LocalMelt 
LocalReAlloc 
LocalShrink 


LocalSize 


LocalUnlock 
LockData 
UnlockData 


Functions Overview 


Frees a local memory block from memory if 
the lock count Is zero. 


Prevents compaction of the local heap. 


Sets the entry count for new handle tables in 
the local heap. 


Locks a block of local memory by increasing 
its lock count. 


Permits compaction of the local heap. 
Reallocates a local memory block. 
Shrinks the local heap. 


Returns the size (in bytes) of a local memory 
block. 


Unlocks a local memory block. 
Locks a data segment in memory. 


Unlocks a data segment. 


2.4.3 Task Functions 


Task functions alter the execution status of tasks, return information 
associated with a task, and retrieve information about the environment 
in which the task is executing. A task is a single Windows application 
call. The following list briefly describes each task function: 


Function 


Catch 


GetCurrentTask 
SetPriority 
Throw 


Yield 


Description 

Copies the current execution environment to 
a, buffer. 

Returns the task handle of the current task. 
Sets the priority of a task. 


Restores the execution environment to the 
specified values. 


Halts the current task and starts any wait- 
ing task. 
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2.4.4 Resource-Manager Functions 


Resource-manager functions find and load application resources from 
a Windows executable file. A resource can be a cursor, icon, bitmap, 
string, or font. The following list briefly describes each resource-manager 


function: 
Function 


AccessResource 


AllocResource 


FindResource 
FreeResource 
LoadAccelerators 
LoadBitmap 
LoadCursor 
LoadIcon 
LoadMenu 
LoadResource 
LoadString 


LockResource 


SetResourceHandler 


SizeofResource 


UnlockResource 
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Description 


Opens the specified resource. 


Allocates uninitialized memory for a 
resource. 


Determines the location of a resource. 
Removes a loaded resource from memory. 
Loads an accelerator table. 

Loads a bitmap resource. 

Loads a cursor resource. 

Loads an icon resource. 

Loads a menu resource. 

Loads a resource. 

Loads a string resource. 


Retrieves the absolute memory address of a 
resource. 


Sets up a function to load resources. 
Supplies the size (in bytes) of a resource. 


Unlocks a resource. 
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2.4.5 String- Translation Functions 


String-translation functions translate strings from one character set 
to another, convert the case of strings, and find adjacent characters in 
a string. The following list briefly describes each string-translation 
function: 


Function Description 

AnsiLower Converts a character string to lowercase. 

AnsiNext Returns a long pointer to the next character in a 
string. 

AnsiPrev Returns a long pointer to the previous character 
in a string. 

AnsiToOem Converts an ANSI string to an OEM character 
string. 

AnsiUpper Converts a character string to uppercase. 

Oem ToAnsi Converts an OEM character string to an ANSI 
string. 


2.4.6 Atom-Manager Functions 


Atom-manager functions create and manipulate atoms. Atoms are integers 
that uniquely identify character strings. They are useful in applications 
that use many character strings and in applications that need to conserve 
memory. Windows stores atoms in atom tables. A local atom table is allo- 
cated in an application’s data segment; it cannot be accessed by other 
applications. The global atom table can be shared, and is useful in applica- 
tions that use dynamic data exchange (DDE). The following list briefly 
describes each atom-manager function: 
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Function Description 

AddAtom Creates an atom for a character string. 

DeleteAtom Deletes an atom if the reference count 1s 
ZeTO. 

FindAtom Retrieves an atom associated with 
a character string. 

GetAtomName Copies the character string associated 
with an atom. 

GlobalAddAtom Creates a global atom for a character 
string. 

GlobalDeleteAtom Deletes a global atom if the reference 
count is zero. 

GlobalFindAtom Retrieves a global atom associated with 
a character string. 

GlobalGetAtom Name Copies the character string associated 
with a global atom. 

InitAtom Table Initializes an atom hash table. 

MAKEINTATOM Casts an integer for use as a function 

| argument, 


2.4.7 Initialization-File Functions 


Initialization-file functions obtain information from and copy information 
to the Windows initialization file, win.intz. The Windows initialization file 
is a special ASCII file that contains keyname-value pairs that represent 
run-time options for applications. The following list briefly describes each 
initialization-file function: 


Function Description 

GetProfileInt Returns an integer value in a section from 
the win.inz file. 

GetProfileString Returns a character string 1n a section 
from the win.inz file. 

WriteProfileString Copies a character string to the win.ini 
file. 
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2.4.8 Communication Functions 


Communication functions carry out communications through the system’s 
serial and parallel I/O ports. The following list briefly describes each com- 


munication function: 
Function 


BuildCommDCB 
ClearCommBreak 
CloseComm 
FlushComm 
GetCommError 


GetCommEventMask 
GetCommState 
OpenComm 


ReadComm 
SetCommBreak 

Set CommEventMask 
SetCommState 
TransmitCommChar 
UngetCommChar 


WriteComm 


Description 
Fills a device control block with control 
codes. 


Clears the communication break state 
from a communication device. 


Closes a communication device after 
transmitting the current buffer. 


Flushes characters from a communication 
device. 


Fills a buffer with the communication 
status. 


Retrieves, and then clears, an event mask. 
Fills a buffer with a device control block. 
Opens a communication device. 


Reads the bytes from a communication 
device into a buffer. 


Sets a break state on the communication 
device. 


Sets an event mask on the communication 
device. 


Sets a communication device to the state 
specified by the device control block. 


Places a character at the head of the 
transmit queue. 


Specifies which character will be the next 
character to be read. 


Writes the bytes from a buffer to a com- 
munication device. 
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2.4.9 Sound Functions 


Sound functions create sound and music for the system’s sound generator. 
The following list briefly describes each sound function: 


Function 


CloseSound 


Count VoiceNotes 


Get ThresholdEvent 


GetThresholdStatus 


OpenSound 
SetSoundNoise 


Set VoiceAccent 
Set VoiceEnvelope 


Set VoiceNote 

Set VoiceQueueSize 
Set VoiceSound 

Set VoiceThreshold 


. StartSound 
StopSound 


SyncAll Voices 
WaitSoundState 
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Description 
Closes the play device after flushing the 
voice queues and freeing the buffers. 


Returns the number of notes in the 
specified queue. 


Returns a long pointer to a threshold 
flag. 


Returns the threshold-event status for 
each voice. 


Opens the play device for exclusive use. 


Sets the source and duration of a noise 
from the play device. 


Places an accent in the voice queue. 


Places the voice envelope in the voice 
queue. 


Places a note in the specified voice 
queue. 


Allocates a specified number of bytes 
for the voice queue. 


Places the specified sound frequency 
and durations in a voice queue. 


Sets the threshold level for a given 
voice. 


Starts playing each voice queue. 


Stops playing all voice queues and 
flushes their contents. 


Places a syne mark in each voice queue. 


Waits until the play driver enters the 
specified state. 


Functions Overview 


2.4.10 Utility Functions 


Utility functions return contents of words and bytes, and create unsigned 
long integers. The following list briefly describes each utility function: 


Function 


HIBY TE 
HIWORD 
LOBYTE 
LOWORD 
MAKELONG 


Description 


Returns the high-order byte of an integer. 
Returns the high-order word of a long integer. 
Returns the low-order byte of an integer. 
Returns the low-order word of a long integer. 


Creates an unsigned long integer. 


2.4.11 File I/O Functions 


File I/O functions create and open files. The following list briefly describes 


each file I/O function: 
Function 


GetTempDrive 


Get TempFileName 
OpenFile 


Description 

Returns the letter of the optimal drive for 
temporary file storage. 

Creates a temporary filename. 


Creates, opens, reopens, or deletes the specified 


file. 
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Introduction 


This chapter contains an alphabetical list of functions from the Microsoft 
Windows application programming interface (API). The documentation 
for each function contains a line illustrating correct syntax, a statement 
about the function’s purpose, a description of its input parameters, and a 
description of its return value. The documentation for some functions con- 
tains additional, important information that an application developer 
needs in order to use the function. 
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int AccessResource(hinstance, hResInfo) 


This function opens the specified resource file and moves the file pointer 
to the beginning of the specified resource, letting an application read 
the resource from the file into its own local memory space. The 
AccessResource function supplies a DOS file handle that can be used 
in subsequent file-read calls to load the resource. The file is opened for 
reading only. 


Applications that use this function must close the resource file after read- 
ing the resource. 


Parameter Type/Description 

hInstance HANDLE Identifies the instance of the module 
whose executable file contains the resource. 

hResInfo HANDLE Identifies the desired resource. This han- 
dle should be created by using the FindResource 
function. 


Return Value 


The return value specifies a DOS file handle to the designated resource file. 
It is -1 if the resource cannot be found. 


Comments 


AccessResource can exhaust available DOS file handles and cause errors 
if the opened file is not closed after the resource is accessed. 


ATOM AddAtom(IpString) 


This function adds the character string pointed to by the [pString param- 
eter to the atom table and creates a new atom that uniquely identifies the 
string. The atom can be used in a subsequent GetAtomName function to 
retrieve the string from the atom table. 


The AddAtom function stores no more than one copy of a given string in 


the atom table. If the string is already in the table, the function returns 
the existing atom value and increases the string’s reference count by one. 


Parameter Type/Description 
lpString LPSTR Points to the character string to be added to 


the table. The string must be an null-terminated char- 
acter string. 
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Return Value 


The return value specifies the newly created atom if the function is suc- 
cessful. Otherwise, it is NULL. 


Comments 


The atom values returned by AddAtom range from C000 to FFFF (hexa- 
decimal). Atoms are case insenscfive. 


short AddFontResource(lpFilename) 


This function adds the font resource from the file named by the [pFilename 
parameter to the Windows font table. The font can subsequently be used 
by any application. 


Parameter Type/ Description 


lnFilename LPSTR Points to a character string that names the 
font-resource file or contains a handle to a loaded 
module. If lpFilename points to the font-resource 
filename, the string must be null-terminated, have the 
DOS filename format, and include the extension. If 
lpFilename contains a handle, the handle is in the low- 
order word and the high-order word is zero. 


Return Value 


The return value specifies the number of fonts added. The return value is 
zero if no fonts are loaded. 


Comments 


Any application that adds or removes fonts from the Windows font table 
should notify other windows of the change by using the SendMessage 
function to send a WM. FONTCHANGE message. The message should be 


sent to all window handles enumerated by the Enum Windows function. 


It is good practice to remove any font resource an application has added 
once the application is through with the resource. 


For a description of font resources, see the Microsoft Windows Program- 
mer’s Learning Guide. 
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void AdjustWindowRect(IpRect, lStyle, bMenu) 


This function computes the required size of the window rectangle based on 
the desired client-rectangle size. The window rectangle can then be passed 
to the CreateWindow function to create a window whose client area is 
the desired size. A client rectangle is the smallest rectangle that com- 
pletely encloses a client area. A window rectangle is the smallest rectangle 
that completely encloses the window. The dimensions of the resulting win- 
dow rectangle depend on the window styles and on whether the window 
has a menu. | | 


Parameter Type/Description 

lpRect LPRECT Points toa RECT data structure that 
contains the coordinates of the client rectangle. 

lStyle long Specifies the window styles of the window whose 
client rectangle is to be converted. 

bMenu BOOL Specifies whether the window has a menu. 


Return Value 


None 


HANDLE AllocResource(hInstance, hResInfo, dwSize) 


This function allocates uninitialized memory for the passed resource. All 
resources must be initially allocated by using the AllocResource func- 
tion. The LoadResource function calls this function before loading the 
resource. 


Parameter Type/ Description 

hInstance HANDLE Identifies the instance of the module 
whose executable file contains the resource. 

hResInfo HANDLE Identifies the desired resource. It is 


assumed that this handle was created by using the 
FindResource function. 


dwSize DWORD Specifies an override size in bytes to allo- 
cate for the resource. The override is ignored if the size 
is zero. 
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Return Value 


The return value identifies the global memory block allocated for the 
resource. 


LPSTR AnsiLower(/pStr) 


This function converts the given character string to lowercase. 


Parameter Type/Description 
lp Str LPSTR Points to a null-terminated character string 
or single character. If the pointer is to a single charac- 


ter, that character is in the low-order byte of the low- 
order word and the high-order word is zero. 


Return Value 
The return value points to a converted character string if the function 


parameter is a character string. Otherwise, it is a 32-bit value that con- 
tains the converted character in the low-order byte of the low-order word, 


Comments 


The AnsiLower function also converts strings obtained from OEM char- 
acter sets. 


LPSTR AnsiNext(lpCurrentChar) 
This function moves to the next character in a string. 
Parameter Type/Description 


lpCurrentChar LPSTR Points to a character in a null-terminated 
string. 


Return Value 


The return value points to the next character in the string, or, if there is 
no next character, to the null character at the end of the string. 
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Comments 
The AnsiNext function is used to move through strings whose characters 


are two or more bytes each (for example, strings that contain characters 
from a Japanese character set). 


LPSTR AnsiPrev(IpStart, lpCurrentChar) 


This function moves to the previous character in a string. 


Parameter Type/Description 

lpStart LPSTR Points to the beginning of the string. 

lpCurrentChar LPSTR Points to a character in a null-terminated 
string. 


Return Value 
The return value points to the previous character in the string, or to the 


first character in the string if the lpCurrentChar parameter is equal to the 
lnStart parameter. 


Comments 
The AnsiPrev function is used to move through strings whose characters 


are two or more bytes each (for example, strings that contain characters 
from a Japanese character set). 


BOOL AnsiToOem(IpAnsiStr, lpOemStr) 


This function translates the string pointed to by the lpAnsiStr parameter 
from the ANSI character set into the OKM-defined character set. 


Parameter Type/ Description 

lpAnsiStr LPSTR Points to a null-terminated string of charac- 
ters from the ANSI character set. 

lpOemStr LPSTR Points to the location where the translated 


string is to be copied. The lpOemStr parameter can be 
the same as IpAnsiStr to translate the string in place. 
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Return Value 


The return value specifies the outcome of the character translation. It is 
nonzero if all characters in the ANSI string have been translated into 
equivalent characters in the OEM character set. It 1s zero if one or more 
characters in the ANSI string have no direct equivalent in the OEM char- 
acter set. In such cases, an arbitrary OEM character is selected for the 
translation. 


LPSTR AnsiUpper(l/pSér) 


This function converts the given character string to uppercase. 


Parameter Type/ Description 


loStr LPSTR Points to a null-terminated character string 
or single character. If the pointer is to a single charac- 
ter, that character is in the low-order byte of the low- 
order word and the high-order word is zero. 


Return Value 


The return value points to a converted character string if the function 
parameter is a character string; otherwise, it is a 32-bit value that con- 
tains the converted character in the low-order byte of the low-order word, 


i fi.) ~ fm, ‘ 
- 7" 


Comments 


The AnsiUpper function also converts strings obtained from OEM char- 
acter sets. 


BOOL AnyPopup( ) 

This function indicates whether or not a pop-up window exists on 

the screen. It searches the entire Windows screen, not just the caller’s 
client area. The AnyPopup function returns nonzero even if a pop-up 
window is completely covered by another window. 


This function has no parameters. 
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Return Value 


The return value is nonzero if a pop-up window exists. Otherwise, it is 
Zero. 


BOOL Arc(hDC, Xi, Yi, X2, Y2, X8, Y8, X4, Yd) 


This function draws an elliptical arc. The center of the arc is the center of 
the bounding rectangle specified by the points X1, Y1 and X2, Y2. The 
arc starts at the point X8, Y3 and ends at the point X4, Y4. The arc is 
drawn using the selected pen and moving in a counterclockwise direction. 
Since an arc does not define a closed area, it is not filled. 


Parameter Type/Description 

ADC HDC Identifies the device context. 

XI short Specifies the logical z-coordinate of the upper- 
left corner of the bounding rectangle. 

Y1 short Specifies the logical ycoordinate of the upper- 
left corner of the bounding rectangle. 

X2 short Specifies the logical 2coordinate of the lower- 
right corner of the bounding rectangle. 

Y2 short Specifies the logical ycoordinate of the lower- 
right corner of the bounding rectangle. 

X83 short Specifies the logical 2coordinate of the arc’s 
starting point. This point does not have to lie exactly 
on the arc. 

Y3 short Specifies the logical y coordinate of the arc’s 
starting point. This point does not have to lie exactly 
on the arc. | 

X4 short Specifies the logical a-coordinate of the arc’s 
endpoint. This point does not have to lie exactly on 
the arc. | 

Y4 short Specifies the logical ycoordinate of the arc’s 
endpoint. This point does not have to le exactly on 
the arc. 
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Return Value 


The return value specifies whether the arc is drawn. It is nonzero if the arc 
is drawn. Otherwise, it is zero. | 


Comments 
The width of the rectangle specified by the absolute value of X2 — X1 


must not exceed 32,767 units. This limit applies to the height of the 
rectangle as well. 
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HDC BeginPaint(hWnd, IpPaint) 


This function prepares the given window for painting and fills the paint 
structure pointed to by the /pPaint parameter with information about the 
painting. 


The paint structure contains a handle to the device context for the win- 
dow, a RECT data structure that contains the smallest rectangle that 
completely encloses the update region, and a flag that specifies whether 
or not the background has been erased. | 


The BeginPaint function automatically sets the clipping region of the 
device context to exclude any area outside the update region. The update 
region is set by the InvalidateRect or InvalidateRgn functions and by 
the system after sizing, moving, creating, scrolling, or any other operation 
that affects the client area. If the update region is marked for erasing, 
BeginPaint sends a WMW~ ERASEBKGND message to the window. 


The BeginPaint function must be called in response to a WM_ PAINT 
message. Each BeginPaint call must have a matching call to the 
EndPaint function. 


Parameter Type/Description 
hWnd HWND Identifies the window to be repainted. 
lpPaint LPPAINTSTRUCT Points to the 


PAINTSTRUCT data structure that is to receive 
painting information, such as the device context for 
the window and the update rectangle. 


Return Value 


The return value identifies the device context for the specified window. 


Comments 


If the caret is in the area to be painted, the BeginPaint function auto- 
matically hides the caret to prevent it being erased. 


BOOL BitBlt(hDestDC, X, Y, nWidth, nHeight, hSrcDC, XSre, 
YSre, dwkop) 


This function moves a bitmap from the source device given by the hSrcDC 
parameter to the destination device given by the hDestDC parameter. The 
XSreand YSre parameters specify the origin on the source device of the 
bitmap that is to be moved. The X, Y, nWidth, and nHeight parameters 
specify the origin, width, and height of the rectangle on the destination 
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device that is to be filled by the bitmap. The dwRop parameter (raster 
operation) defines how the bits of the source and destination are com- 


bined. 


Parameter Type/Description 


hDestDC HDC Identifies the device context that is to receive 
the bitmap. 

xX short Specifies the logical 2-coordinate of the upper- 
left. corner of the destination rectangle. 

Y short Specifies the logical y-coordinate of the upper- 
left corner of the destination rectangle. 

nWidth short Specifies the width (in logical units) of the des- 
tination rectangle and source bitmap. 

nHeight short Specifies the height (in logical units) of the des- 
tination rectangle and source bitmap. 

hSrcDC HDC Identifies the device context from which the 


bitmap will be copied. It must be NULL if the dwRop 
parameter specifies a raster operation that does not 
include a source. 


XSre short Specifies the logical zcoordinate of the upper- 
left corner of the source bitmap. 

YSrc short Specifies the logical ycoordinate of the upper- 
left corner of the source bitmap. 

dwRop DWORD | Specifies the raster operation to be per- 


formed. Raster-operation codes define how the graphic 
device interface (GDI) combines colors in output opera- 
tions that involve a current brush, a possible source bit- 
map, and a destination bitmap. For a list of raster- 
operation codes, see Table 3.1. 


Return Value 


The return value specifies whether or not the bitmap is drawn. It is 
nonzero if the bitmap is drawn. Otherwise, it is zero. 


Comments 


GDI transforms the nWidth and nHeight parameters, once by using the 
destination display context, and once by using the source display context. 
If the resulting extents do not match, GDI uses the StretchBlt function 
to compress or stretch the source bitmap as necessary. 
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If destination, source, and pattern bitmaps do not have the same color 
format, the BitBIt function converts the source and pattern bitmaps to 
match the destination. The foreground and background colors of the des- 
tination are used in the conversion. 


If BitBlt converts monochrome bitmaps to color, it sets white bits (1) to 
the background color and black bits (0) to the foreground color. The fore- 
ground and background colors of the destination device context are used. 
To convert color to monochrome, BitBlt sets pixels that match the back- 
ground color to white (1), and sets all other pixels to black (0). The fore- 
ground and background colors of the color-source device context are used. 


The foreground color is the current text color for the specified device con- 
text, and the background color is the current background color for the 


specified device context. 


Not all devices support the BitBlt function. For more information, see the 
RC_BITBLT raster capability in the GetDeviceCaps function, later in 


this chapter. 


Table 3.1 lists the raster-operation codes for the dwRop parameter: 


Table 3.1 


Raster Operations 


Code 
SRCPAINT 


SRCCOPY 


SRCAND 


SRCINVERT 


SRCERASE 


NOTSRCCOPY 


NOTSRCERASE 
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Description 


Combines pixels of the destination and 
source bitmaps using the Boolean OR 
operator. 


Copies the source bitmap to the destination 
bitmap. 

Combines pixels of the destination and 
source bitmaps using the Boolean AND 
operator. 


Combines pixels of the destination and 
source bitmaps using the Boolean XOR 
operator. 


Inverts the destination bitmap and com- 
bines the result with the source bitmap 
using the Boolean AND operator. 


Copies the inverted source bitmap to the 
destination. 


Inverts the result of combining the des- 
tination and source bitmaps using the 
Boolean AND operator. 


Bring WindowToTop 


Table 3.1 (continued) 
Code Description 


MERGECOPY Combines the pattern and the source 
bitmap using the Boolean AND operator. 


MERGEPAINT Combines the inverted source bitmap with 
the destination bitmap using the Boolean 
OR operator. 


PATCOPY Copies the pattern to the destination 
bitmap. 
PATPAINT Combines the inverted source bitmap with 


the pattern using the Boolean OR operator. 
Combines the result of this operation with 
the destination bitmap using the Boolean 
OR operator. 


PATINVERT Combines the destination bitmap with the 
pattern using the Boolean OR operator. 


DSTINVERT Inverts the destination bitmap. 
BLACKNESS Turns all output black. 
WHITENESS Turns all output white. 


For a complete list of the raster-operation codes, see Appendix A, “Binary 
and Ternary Raster-Operation Codes and Definitions.” 


void BringWindowToTop(h Wnd) 
This function brings a pop-up or child window to the top of a stack of 
overlapping windows. The Bring WindowToTop function should be used 


to uncover any window that is partially or completely obscured by any 
overlapping windows. 


Parameter Type/Description 


hWnd HWND _Identifies the pop-up or child window that is 
| to be brought to the top. 


Return Value 


None 
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short BuildCommDCB(IpDef, lpDCB) 


This function translates the definition string specified by the /pDef param- 
eter into appropriate device-control block codes and places these codes 
into the block pointed to by the /pDCB parameter. 


Parameter Type/Description 


lpDef LPSTR Points to a null-terminated character string 
that specifies the device-control information for a 


device. The string must have the same form as the 
DOS MODE command-line parameter. 


lpDCB DCB FAR * Points to the DCB data structure that 
is to receive the translated string. The structure defines 
the control setting for the serial-communication device. 


Return Value 


The return value specifies the result of the function. It is zero if the string 
is translated. It is negative if an error occurs. 
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BOOL CallMsgFilter(lpMsg, nCode) 


This function passes the given message and code to the current message 
filter function. The message filter function is an application-specified func- 
tion that examines and modifies all messages. An application specifies the 
function by using the Set WindowsHook function. 


Parameter Type/Description 


lpMsg LPMSG Points to an MSG data structure that 


contains the message to be filtered. 


nCode int Specifies a code used by the filter function to 
determine how to process the message. 


Return Value 


The return value specifies the state of message processing. It is FALSE if 
the message should be processed. It is TRUE if the message should not be 
processed further. 


Comments 


The CallMsgFilter function is usually called by Windows to let applica- 
tions examine and control the flow of messages during internal processing 
in menus and scroll bars or when moving or sizing a window. 


Values given for the nCode parameter must not conflict with any of 
the MSGF. and HC_ values passed by Windows to the message filter 
function. 


long CallWindowProc(lpPrevWndFunc, hWnd, wMsg, wParam, lParam) 


This function passes message information to the function specified by the 
lopPrevWndF unc parameter. The CallWindowProc function is used for 
window subclassing. Normally, all windows with the same class share the 
same window function. A subclass is a window or set of windows belonging 
to the same window class whose messages are intercepted and processed by 
another function (or functions) before being passed to the window function 
of that class. 


The Set WindowLong function creates the subclass by changing the win- 
dow function associated with a particular window, causing Windows to 
call the new window function instead of the previous one. Any messages 
not processed by the new window function must be passed to the pre- 
vious window function by calling CallWindowProc. This allows a chain 
of window functions to be created. 
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Parameter Type/Description 


loPrevoWndFune FARPROC Is the procedure-instance address of the 


previous window function. 


hWnd HWND Identifies the window that passes the 
message. 

wMsg unsigned Specifies the message number. 

wParam WORD Specifies additional message-dependent 
information. 

lParam LONG Specifies additional message-dependent 
information. 


Return Value 


The return value specifies the result of the message processing. The pos- 
sible return values depend on the message sent. 


int Catch(lpCatchBu/) 
This function catches the current execution environment and copies it 
to the buffer pointed to by the ipCatchBuf parameter. The execution 


environment is the state of all system registers and the instruction 
counter. 


Parameter Type/Description 
lnCatchBuf LPCATCHBUF Points to the CATCHBUF struc- 


ture that will receive the execution environment. 


Return Value 


The return value specifies whether the execution environment is copied to 
the buffer. It is zero if the environment is copied to the buffer. 


Comments 


The Throw function uses the buffer to restore the execution environment 
to its previous values. | 


The Catch function is similar to the C run-time SetJmp function (which 
is incompatible with the Windows environment). 
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BOOL ChangeClipboardChain(hWnd, hWndNezt) 


This function removes the window specified by the hWnd parameter from 
the chain of clipboard viewers and makes the window specified by the 
hWndNexzt parameter the descendant of the hWnd parameter’s ancestor in 
the chain. 


Parameter Type/Description 


hWnd HWND Identifies the window that is to be removed 
from the chain. The handle must previously have been 
passed to the SetClipboard Viewer function. 


hWndNezxt HWND _ Identifies the window that follows hWnd in 
the clipboard-viewer chain (this is the handle returned 
by SetClipboard Viewer, unless the sequence was 
changed in response to a WM_ CHANGECBCHAIN 


message). 
Return Value 


The return value specifies the status of the hWnd window. It is nonzero if 
the window is found and removed. Otherwise, it is zero. 


BOOL ChangeMenu(hMenu, ae lpNewltem, wlDNewltem, 
wChange) 


This function appends, inserts, deletes, or modifies a menu item in the 
menu given by the hAMenu parameter. The wlDChangeltem, lpNewltem, 
wlDNewltem, and wChange parameters define which item to change and 
how to change it. 


Parameter Type/Description 
hMenu HMENU Identifies the menu to be changed. 


wlDChangeltem WORD Specifies the item to be changed. If 
MF_ BYPOSITION is specified, the wlDChangeltem 
parameter gives the position of the menu item to 
be changed (the first item is at position zero). If 
MF_ BYCOMMAND is specified instead, wl, Changeltem 
specifies the menu-item ID. The menu-item ID can 
specify any pop-up menu item (that is, an item in a 
pop-up menu associated with an item of hMenu). If nei- 
ther flag is given, the default is MF_ BYCOMMAND. 
When MF_INSERT is used, wlDChangeltem identifies 
the item before which the new item is to be inserted. 


When MF_ APPEND is used, wlDChangeltem is NULL. 
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lnNewltem LPSTR Points to either a handle to a bitmap or to a 
string. The /pNewltem parameter is never a handle to a 
menu. The MF_ POPUP flag applies to the wlDNewltem 
parameter only. The IpNewltem parameter contains the 
following values: 


Values Meaning 


MF_ BITMAP Points to a bitmap. The low-order 
word contains a handle that 
identifies the bitmap. The high- 
order word is zero. 


MF_ STRING Points to a character string. 


The default is MF_STRING. A NULL value for 
lpNewltem creates a horizontal break (the same effect 
as using the MF_SEPARATOR flag). 


wlDNewltem WORD Specifies the new menu item. The 
wlDNewltem parameter is either a new menu-item ID, or 
a handle to a pop-up menu. It is never a menu-item posi- 
tion. The MF. BYPOSITION and MF_ BYCOMMAND 
flags apply to the wlDChangeltem parameter only. 


wChange WORD Specifies how to change the menu. It consists 
of one or more of the values given in Table 3.2. 


Return Value 


The return value specifies the status of the menu change. It is nonzero if 
the change is successful. Otherwise, it is zero. 


Comments 


When the user selects a menu item, it is automatically highlighted. A 
menu is highlighted when it is displayed in inverse video fon a mono- 
chrome display). To control highlighting of menu items, use the 
HiliteMenultem function. 


Anytime a menu changes (whether or not the window it resides in is 
displayed) the application should call DrawMenuBar. The Change- 
Menu function is useful for inserting, deleting, changing, and appending 
menu items, and for setting the attributes of the new or changed items. 
Note that to change the attributes of existing menu items, it is much 
faster to use the CheckMenultem and EnableMenultem functions. 


The MF_ SEPARATOR flag has the special property that if the 


wlDChangeltem parameter is zero, the separator is appended to the 
end of the menu even if the MF_INSERT flag is in effect. 
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Each of the following groups lists flags that are mutually exclusive and 
should not be used together: 


e MF. APPEND, MF. CHANGE, MF. DELETE, MF_INSERT, and 
MF. REMOVE © 


¢ MF BYCOMMAND and MF_BYPOSITION 
¢ MF_DISABLED, MF_ENABLED, and MF_ GRAYED 
¢ MF_BITMAP, MF_ POPUP, and MF_STRING 

e MF_MENUBARBREAK and MF_MENUBREAK 

e MF_CHECKED and MF_ UNCHECKED 


Table 3.2 lists the flags used with the wChange parameter. These values 
can be combined using the bitwise OR operator: 


Table 3.2 

ChangeMenu Flags 

Value Meaning 

MF_ APPEND Appends the new item to the end of the menu. 

MF_ BITMAP Uses a bitmap as the item. The low-order word of 
the [pltem parameter is a handle that specifies the 
bitmap. 

MF_ BYCOMMAND Specifies that the w[DChangeltem parameter gives 
the menu-item ID number (default). 

MF_ BYPOSITION Specifies that the wlDChangeltem parameter gives 


the position of the menu item to be changed, rather 
than gives an ID number. 


MF_ CHANGE Changes or replaces the specified item. 

MF_ CHECKED Places a checkmark next to the item (pop-up menu 
item only). | 

MF. DELETE Deletes the item. 

MF_ DISABLED Disables the item without changing its appearance 
(it cannot be selected). 

MF_ ENABLED Enables the item, allowing it to be selected (default). 

MEF. GRAYED Disables and grays the item to show that it cannot 
be selected. 

MF_ INSERT Inserts a new item just before the specified item 
(default). 


MF_ MENUBARBREAK ~~ Same as MF.. MENUBREAK, except that for pop-up 
menus, separates the new column from the old col- 
umn with a vertical dividing line. 
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Table 3.2 (continued) 


Value Meaning 


MF_MENUBREAK Places the item on a new line (for static, menu bar, 
menus). For pop-up menus, places the item in a new gia 
column, with no dividing line between the columns. 
MF_ POPUP Associates a pop-up menu with a menu item. The 
wilDNewltem parameter is a handle to the menu. 
This can only be used with top-level menu items. 


MF. REMOVE Removes the item but does not delete it. 


MF_ SEPARATOR Draws a horizontal dividing line. Can only be used 
in pop-up menus. The line cannot be enabled, 
checked, grayed, or highlighted. The lpNewltem 
and wlDNewltem parameters are ignored. 

MF. STRING Uses a string as the item (default). The lpNewltem 
parameter is a long pointer to a null-terminated 
character string. 

MF_ UNCHECKED _ Does not place a checkmark next to the item 
(default). 


void CheckDlgButton(hDlg, nIDButton, wCheck) 


This function places a checkmark next to or removes a checkmark from 
a button control, or changes the state of a three-state button. The 
CheckD]gButton function sends a BMU_SETCHECK message to the 
button control that has the specified ID in the given dialog box. 


Parameter Type/ Description 

hDig HWND Identifies the dialog box that contains the 
button. 

nlDButton int Specifies the button control to be modified. 

wCheck WORD Specifies the action to take. If the wCheck 


parameter is nonzero, the CheckDlgButton function 
places a checkmark next to the button; if zero, the 
checkmark is removed. For three-state buttons, if 
wCheck is 2, the button is grayed; if wCheck is 1, it is 
checked; if wCheck is 0, the checkmark 1s removed. 


Return Value 


None 
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BOOL CheckMenultem(hMenu, wIDCheckItem, wCheck) 


This function places checkmarks next to or removes checkmarks from 
menu items in the pop-up menu specified by the hMenu parameter. The 
wlDCheckltem parameter specifies the item to be modified. 


Parameter Type/Description | 
hMenu HMENU _ Identifies the menu. 
wlDCheckltem ‘WORD Specifies the menu item to be checked. 
wCheck WORD Specifies how to check the menu item and 


how to determine the item’s position in the menu. 
The wCheck parameter can be a combination of the 
MF_ CHECKED or MF_ UNCHECKED with 

MF_ BYPOSITION or MF_ BYCOMMAND flags. 
These flags can be combined by using the bit- 

wise OR operator. They have the following 
meanings: 


Value Meaning 
MF_ BYCOMMAND. Specifies that the wlDCheckltem 


parameter gives the menu-item 
ID (MF_ BYCOMMAND is the 
default). 


MF. BYPOSITION — Specifies that the wlDCheckltem 
parameter gives the position of 
the menu item (the first item is 
at position zero). 


MF_ CHECKED Adds checkmark. 
MF. UNCHECKED Removes checkmark. 


Return Value 


The return value specifies the previous state of the item. It is either 


MF CHECKED or MF_ UNCHECKED. 


Comments 


The wlDCheckltem parameter may identify a pop-up menu item as well as 
a menu item. No special steps are required to check a pop-up menu item. 


Top-level menu items cannot be checked. 
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void CheckRadioButton(hDilg, nIDFirstButton, n[DLastButton, 
nIDCheckButton) 


This function checks the radio button specified by the nJDCheckButton 
parameter and removes the checkmark from all other radio buttons in 

the group of buttons specified by the nIDFirstButton and nlDLastButton 
parameters. The CheckRadioButton function sends a BM_ SETCHECK 
message to the radio-button contro] that has the specified ID in the given 
dialog box. 


Parameter Type/Description 


hDlg HWND Identifies the dialog box. 


nlDFirstButton int Specifies the integer identifier of the first radio 
button in the group. 


nlDLastButton int Specifies the integer identifier of the last radio 
button in the group. 


nlDCheckButton int Specifies the integer identifier of the radio button 
to be checked. 


Return Value 


None 


HWND ChildWindowFromPoint(hWndParent, Point) 


This function determines which, if any, of the child windows belonging to 
the given parent window contains the specified point. 


Parameter Type/Description 


hWndParent HWND Identifies the parent window. 


Point POINT Specifies the client coordinates of the point 
to be tested. 


Return Value 


The return value identifies the child window that contains the point. It is 
NULL if the given point lies outside the parent window. If the point is 
within the parent window but is not contained within any child window, 
the handle of the parent window is returned. 
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BOOL Chord(hDC, X1, Y1, X2, Y2, X3, Y3, X4, Y4) 


This function draws a chord (a region bounded by the intersection of an 
ellipse and a line segment). The X1, Yi and X2, Y2 parameters specify the 
upper-left and lower-right corners, respectively, of a rectangle bounding 
the ellipse that is part of the chord. The X8, YS and X4, Y4 parameters 
specify the endpoints of a line that intersects the ellipse. The chord is 
drawn by using the selected pen and filled by using the selected brush. 


Parameter Type/ Description 

hDC HDC | Identifies the device context in which the chord 
will appear. 

X1 short Specifies the zcoordinate of the bounding 
rectangle’s upper-left corner. 

Y1 short Specifies the y-coordinate of the bounding 
rectangle’s upper-left corner. 

X2 short Specifies the z-coordinate of the bounding 
rectangle’s lower-right corner. 

Y2 short Specifies the ycoordinate of the bounding 
rectangle’s lower-right corner. 

X8 short Specifies the s-coordinate of one end of the line 
segment. 

Y3 short Specifies the ycoordinate of one end of the line 
segment. 

X4 short Specifies the coordinate of one end of the line 
segment. 

Y4 short Specifies the ycoordinate of one end of the line 
segment. 


Return Value 


The return value specifies whether or not the arc is drawn. It is nonzero if 
the arc is drawn. Otherwise, it is zero. 


short ClearCommBreak(nCid) 


This function restores character transmission and places the transmission 
line in a nonbreak state. 


Parameter Type/ Description 


nCid int Specifies the communication device to be restored. 
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Return Value 


The return value specifies the result of the function. It is zero if the func- 
tion is successful. It is negative if the nCid parameter is not a valid device. 


void ClientToScreen(hWnd, [pPoint) 


This function converts the client coordinates of a given point on the dis- 
play to screen coordinates. The Client ToScreen function uses the client 
coordinates in the POINT data structure, pointed to by the lpPoint 
parameter, to compute new screen coordinates; it then replaces the coordi- 
nates in the structure with the new coordinates. The new screen coordi- 
nates are relative to the upper-left corner of the system display. 


Parameter Type/Description 


hWnd HWND Identifies the window whose client area will 
be used for the conversion. 
lpPotnt LPPOINT Points toa POINT data structure that 


contains the client coordinates to be converted. 


Return Value 


None 


Comments 


The ClientToScreen function assumes that the given point 1s in client 
coordinates and is relative to the given window. 


void ClipCursor(lpRect) 


This function confines the system cursor to the rectangle on the display 
screen given by the /pRect parameter. If a subsequent cursor position, 
given with the SetCursorPos function or the mouse, lies outside the 
rectangle, Windows automatically adjusts the position to keep the cursor 
inside. If lpRect is NULL, the cursor is free to move anywhere on the 
display screen. 


Parameter Type/Description 
lpRect LPRECT Points toa RECT data structure that 


contains the screen coordinates of the upper-left and 
lower-right corners of the confining rectangle. 
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Return Value 


None 


Comments 
The system cursor is a shared resource. An application that has confined 


the cursor to a given rectangle must free it before relinquishing control to 
another application. 


BOOL CloseClipboard( ) 

This function closes the clipboard. The CloseClipboard function should 
be called when a window has finished examining or changing the clipboard. 
It lets other applications access the clipboard. 


This function has no parameters. 


Return Value 


The return value specifies whether the clipboard is closed. It is nonzero if 
the clipboard is closed, Otherwise, it is zero. 


short CloseComm(nCid) 
This function closes the communication device specified by the nCid 
parameter and frees any memory allocated for the device’s transmit 


and receive queues. All characters in the output queue are sent before 
the communication device is closed. 


Parameter Type/Description 
nCid int Specifies the device to be closed. 


Return Value 


The return value specifies the result of the function. It is zero if the device 
is closed. It is negative if an error occurred. 


HANDLE CloseMetaFile(hDC) 


This function closes the metafile device context and creates a metafile 
handle that can be used to play the metafile by using the PlayMetaFile 
function. 
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Parameter Type/Description 


hDC HANDLE Identifies the metafile device context to be 


closed. 


Return Value 


The return value identifies the metafile if the function is successful. Other- 
wise, it is NULL. 


void CloseSound{ ) 

This function closes access to the play device and frees the device for 
opening by other applications. The CloseSound function flushes all 
voice queues and frees any buffers allocated for these queues. 


This function has no parameters. 


Return Value 


None 


void CloseWindow(hWnda) 
This function minimizes the specified window. If the window is an over- 
lapped window, it is minimized by removing the client area and caption 


of the open window from the display screen and moving the window’s 
icon into the icon area of the screen. 


Parameter Type/Description | 

hWnd HWND Identifies the window to be minimized. 
Return Value 

None 


Comments 


This function has no effect if the hWnd parameter is a handle to a pop-up 
or child window. 
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short CombineRgn(hDestRgn, hSrcRgn1, hSrcRgn2, nCombineMode) 


This function creates a new region by combining two existing regions. The 
method used to combine the regions is specified by the nCombineMode 


parameter. 

Parameter Type/Description 

hDestRgn HRGN Identifies an existing region that will be 
replaced by the new region. 

hSrcRgni HRGN Identifies an existing region. 

hSrcRgn2 HRGN Identifies an existing region. 


nCombineMode short Specifies the operation to be performed on the 
two existing regions. It can be any one of the following 


values: 
Value 
RGN AND 


RGN_ COPY 


RGN_ DIFF 


RGN_ OR 


RGN_ XOR 


Return Value 


Meaning 


Uses overlapping areas of both 


regions (intersection). 


Creates a copy of region I 
(identified by ASrcRgn1). 


Saves the areas of region 1 
(identified by the hSrckgn1 
parameter) that are not part 
of region 2 (identified by the 
hSrcRgn2 parameter). 


Combines all of both regions 
(union). | 


Combines both regions but 
removes overlapping areas. 


The return value specifies the type of the resulting region. It can be any 


one of the following values: 


COMPLEXREGION New region has overlapping borders. 
ERROR No new region created. 


NULLREGION 
SIMPLEREGION 


New region 1s empty. 


New region has no overlapping borders. 
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HANDLE CopyMetaFile(hSrcMetaFile, lpFilename) 
This function copies the source metafile to the file pointed to by 


the IpFilename parameter and returns a handle to the new metafile. 
If lpFilename is NULL, the source is copied to a memory metafile. 


Parameter Type/Description 


hSrcMetaFile | HANDLE Identifies the source metafile. 


loFilename LPSTR Points to a null-terminated character string 
that specifies the file that is to receive the metafile. 


Return Value 


The return value identifies the new metafile. 


int CopyRect(IlpDestRect, lpSourceRect) 


This function copies the rectangle pointed to by the lpSourceRect parame- 
ter to the RECT data structure pointed to by the [pDestRect parameter. 


Parameter  Pype/Description 


lpDestRect LPRECT Points toa RECT data structure. 
lpSourceRect LPRECT Points toa RECT data structure. 


Return Value 


Although the CopyRect function return type is an integer, the return 
value is not used and has no meaning. 


int CountClipboardFormats( ) 


This function retrieves a count of the number of formats the clipboard 
can render. 


This function has no parameters. 


Return Value 


The return value specifies the number of data formats in the clipboard. 
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int Count VoiceNotes(n Voice) 


This function retrieves a count of the number of notes in the speci- 
fied queue. Only those queue entries that result from calls to the 
Set VoiceNote function are counted. 


Parameter Type/ Description 


nVotce int Specifies the voice queue to be counted. The first 
voice queue 1s numbered 1. 


Return Value 


The return value specifies the number of notes in the given queue. 
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HBITMAP CreateBitmap(nWidth, nHeight, nPlanes, nBitCount, 
lp Bits) 


This function creates a bitmap that has the specified width, height, and 
bit pattern. The bitmap can subsequently be selected as the current bit- 
map for a memory display by using the SelectObject function. 


Although a bitmap cannot be copied directly to a display device, the 
BitBlt function can copy it from a memory display context (in which it 
is the current bitmap) to any compatible device. 


Parameter Type/Description 

nWidth short Specifies the width (in pixels) of the bitmap. 

nHeight — short Specifies the height (in pixels) of the bitmap. 

nPlanes BYTE Specifies the number of color planes in the bit- 
sea Each plane has nWidth X nHeight X nBitCount 

its. 

nBitCount BYTE Specifies the number of color bits per display 
pixel. 

ln Bits LPSTR Points to a short-integer array that contains 


the initial bitmap bit values. If it is NULL, the new bit- 
map is left uninitialized. For more information, see the 
description of the bmBits field in the BITMAP data 
structure in Chapter 6, “Data Types and Structures.” 
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Return Value 


The return value identifies a bitmap if the function is successful. Other- 
wise, it is NULL. 


HBITMAP CreateBitmapIndirect(IpBitmap) 


This function creates a bitmap that has the width, height, and bit pat- 
tern given in the data structure pointed to by the /pBitmap parameter. 
Although a bitmap cannot be directly selected for a display device, it can 
be selected as the current bitmap for a memory display and copied to any 
compatible display device by using the BitBlt function. 


Parameter Type/Description 


IpBitmap BITMAP FAR * Points to a BITMAP data struc- 


ture that contains information about the bitmap. 


Return Value 


The return value identifies a bitmap if the function is successful. Other- 


wise, it is NULL. 


HBRUSH CreateBrushIndirect(lpLogBrush) 
This function creates a logical brush that has the style, color, and pattern 


given in the data structure pointed to by the IpLogBrush parameter. The 
brush can subsequently be selected as the current brush for any device. 


Parameter Type/Description 


loLogBrush LOGBRUSH FAR * Points to a LOGBRUSH data 
structure that contains information about the brush. 


Return Value 


The return value identifies a logical brush if the function is successful. 


Otherwise, it is NULL. 


Comments 


The BS_INDEXED style ensures that each of the first eight indexed 
brushes will always be unique on any device. 
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void CreateCaret(hWnd, hBitmap, nWidth, nHeight) 


This function creates a new shape for the system caret and assigns owner- 
ship of the caret to the given window. The caret shape can be a line, block, 
or bitmap as defined by the hBztmap parameter. If hBitmap is a bitmap 
handle, the nWidth and nHezght parameters are ignored; the bitmap 
defines its own width and height. (The bitmap handle must have been pre- 
viously created by using either the CreateBitmap or LoadBitmap func- 
tion.) If ABstmap is NULL or 1, nWidth and nHezght give the caret’s width 
and height (in logical units); the exact width and height (in pixels) depend 
on the window’s mapping mode. 


If nWidth or nHezght is zero, the caret width or height 1s set to the sys- 
tem’s window-border width or height. Using the window-border width 
or height guarantees that the caret will be visible on a high-resolution 
display. 


The CreateCaret function automatically destroys the previous caret 
shape, if any, regardless of which window owns the caret. Once created, 
the caret is initially hidden. To show the caret, the ShowCaret function 
must be called. 


Parameter Type/Description 

hWnd HWND Identifies the window that owns the new 
caret. 

hBitmap HBITMAP Identifies the bitmap that defines the 


caret shape. If hBitmap is NULL, the caret is solid; if 
hBitmap is 1, the caret is gray. 


nWidth int Specifies the width of the caret (in logical units). 
nHeight int Specifies the height of the caret (in logical units). 


Return Value 


None 


Comments 


The system caret is a shared resource. A window should create a caret only 
when it has the input focus or is active. It should destroy the caret before 
losing the input focus or becoming inactive. 


The system’s window-border width or height can be retrieved by using 


the GetSystem Metrics function with the SM_- CXBORDER and 
SM_ CYBORDER indexes. 


177 


CreateCompatibleBitmap 


HBITMAP CreateCompatibleBitmap(hDOC, nWidth, nHeight) 


This function creates a bitmap that is compatible with the device specified 
by the ADC parameter. The bitmap has the same number of color planes 
or bits-per-pixel format as the specified device. It can be selected as the 
current bitmap for any memory device that is compatible with the one 


specified by hDC. 


If hDC is a memory device context, the bitmap returned has the same for- 
mat as the currently selected bitmap in that device context. A memory 
device context is a block of memory that represents a display surface. It 
can be used to prepare images in memory before copying them to the 
actual display surface of the compatible device. 


When a memory device context is created, GDI automatically selects a 
monochrome stock bitmap for it. 


Since a color memory device context can have either color or mono- 
chrome bitmaps selected, the format of the bitmap returned by the 
CreateCompatibleBitmap function is not always the same; however, 
the format of a compatible bitmap for a nonmemory device context is 
always in the format of the device. 


Parameter Type/ Description 

hDC HDC Identifies the device context. 

n Width short Specifies the width (in bits) of the bitmap. 
nHeight short Specifies the height (in bits) of the bitmap. 


Return Value 


The return value identifies a bitmap if the function is successful. Other- 
wise, it is NULL. 


HDC CreateCompatibleDCO(hDC) 


This function creates a memory, device context that is compatible with the 
device specified by the hDC parameter. A memory device context is a block 
of memory that represents a display surface. It can be used to prepare 
images In memory before copying them to the actual device surface of the 
compatible device. 
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When a memory device context is created, GDI automatically selects a 
1 X 1 monochrome stock bitmap for it. 


Parameter Type/Description 


hDC HDC Identifies the device context. If hDC'is NULL, 
the function creates a memory device context that is 
compatible with the system display. 


Return Value 


The return value identifies the new memory device context if the function 
is successful. Otherwise, it 1s NULL. 


Comments 


_ This function can only be used to create compatible device contexts for 
devices that support raster operations. For more information, see the 
RC_BITBLT raster capability in the GetDeviceCaps function, later in 
this chapter. | 


GDI output functions can be used with a memory device context only if a 
bitmap has been created and selected into that context. 


HDC CreateDC(/pDriverName, IpDeviceName, lpOutput, lpInitData) 


This function creates a device context for the specified device. The 
lpDriverName, lpDeviceName, and [pOutput parameters specify the device 
driver, device name, and physical output medium (file or port), respec- 
tively. 


Parameter Type/Description 


lpDriverName LPSTR Points to a null-terminated character string 
that specifies the DOS filename (without extension) of 
the device driver (for example, EPSON). 


lpDeviceName LPSTR Points to a null-terminated character string 
- that specifies the name of the specific device to be sup- 
ported (for example, EPSON FX-80). The IpDeviceName 
parameter is used if the module supports more than one 
device. 


lpOutput LPSTR Points to a null-terminated character string 
that specifies the DOS file or device name for the physi- 
cal output medium (file or output port). 
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lpInitData LPSTR Points to device-specific initialization data 
for the device driver. The lp/nitData parameter must be 
NULL if the device driver is to use the default initializa- 
tion i any) specified by the user through the control 
panel, 


Return Value 


The return value identifies a device context for the specified device if the 
function is successful. Otherwise, it is NULL. 


Comments 


DOS device names follow DOS conventions; an ending colon (:) is recom- 
mended, but optional. Windows strips the terminating colon so that a 
device name ending with a colon is mapped to the same port as the 

same name without a colon. The driver and port names must not contain 
leading or trailing spaces. 


HWND CreateDialog(hInstance, lp TemplateName, hWndParent, 
lpDialogF'unc) 


This function creates a modeless dialog box that has the size, style, and 
controls defined by the dialog-box template given by the lp TemplateName 
parameter. The hWndParent parameter identifies the application win- 
dow that owns the dialog box. The dialog function pointed to by the 
yeas unc parameter processes any messages received by the dia- 

og box. 


The CreateDialog function sends a WM_INITDIALOG message to the 
dialog function before displaying the dialog box. This message allows 
the dialog function to initialize the dialog-box controls. 


CreateDialog returns immediately after creating the dialog box. It does 
not wait for the dialog box to begin processing input. 


Parameter Type/Description 


hInstance HANDLE §Identifies an instance of the module whose 
executable file contains the dialog-box template. 


lpTemplateName LPSTR Points to a character string that names 
the dialog-box template. The string must be a null- 
terminated character string. 


hWndParent HWND _ssIdentifies the window that owns the 
dialog box. 
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lpDialogFunc FARPROC Is the procedure-instance address for the 
dialog function. See the following “Comments” section 
for details. 


Return Value 


The return value identifies the dialog box. It is -1 if the function cannot 
create the dialog box. Zt is the window handle of fhe dialog lox, 


Comments 


Use the WS. VISIBLE style for the dialog-box template if the dialog box 
should appear in the parent window upon creation. 


Use the Destroy Window function to destroy a dialog box created by the 
CreateDialog function. 


The callback function must use the Pascal calling convention and must be 
declared FAR. The callback function must have the following form: 


HWND FAR PASCAL DialogFunc(hWnd, wMsg, wParam, lParam) 
HWND hWnd; 

unsigned wilfsq; 

WORD wParam; 

DWORD [Param; 


DialogFunc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Definition 

hWnd Identifies the dialog box that receives the message. 

wMsg Specifies the message number. 

wParam Specifies 16 bits of additional message-dependent infor- 
mation. 

[Param Specifies 32 bits of additional message-dependent infor- 
mation. 


Return Value 


The dialog function should return nonzero if the function processes the 
message, and zero if it does not. 
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Comments 


The dialog function is used only if the dialog class is used for the dialog 
box. This is the default class and is used if no explicit class is given in the 
dialog-box template. Although the dialog function is similar to a window 
function, it must not call the DefWindowProc function to process 
unwanted messages. Unwanted meses are pores internally by the 
dialog-class window function. ,__ a ae 


The dialog-function address, passed as the lpDialogF'unc parameter, must 
be created by using the MakeProclInstance function. 


HWND CreateDialogIndirect(hInstance, lpDialogTemplate, 
hWndParent, lpDialogFunc) 


This function creates a modeless dialog box that has the size, style, and 
controls defined by the dialog-box template given by the lpDialogTemplate 
parameter. The hWndParent parameter identifies the application win- 
dow that owns the dialog box. The dialog function pointed to by the — 
ieee unc parameter processes any messages received by the dia- 

og box. 


The CreateDialogIndirect function sends a WM_INITDIALOG message 
to the dialog function before displaying the dialog box. This message 
allows the dialog function to initialize the dialog-box controls. 


CreateDialogIndirect returns immediately after creating the dialog box. 
It does not wait for the dialog box to begin processing input. 


Parameter Type/Description 


hInstance HANDLE _ Identifies an instance of the module whose 
executable file contains the dialog-box template. 

lpDialogTemplate 
LPSTR Points to a dialog-box template structure. 


hWndParent HWND Identifies the window that owns the 
dialog box. 


lpDialogF'unc FARPROC Is the procedure-instance address of the 
dialog function. See the following “Comments” section 
for details. 
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Return Value 


The return value identifies the dialog box. It is NULL if the function can- 
not create either the dialog box or any controls in the dialog box. 


I+is the window handle of fhe Chialog 40x. 


Comments 


Use the WS_ VISIBLE style in the dialog-box template if the dialog box 
should appear in the parent window upon creation. 


The callback function must use the Pascal calling convention and must be 
declared FAR. The callback function must have the following form: 


HWND FAR PASCAL DialogFunc(hWnd, wMsg, wParam, lParam) 
HWND hWnd; 

unsigned whsq; 

WORD wParam; 

DWORD [Param; 


DialogF unc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Definition 

hWnd Identifies the dialog box that receives the message. 

wMsg Specifies the message number. 

wParam Specifies 16 bits of additional message-dependent infor- 
mation. 

[Param Specifies 32 bits of additional message-dependent infor- 
mation. 


Return Value 


The dialog function should return nonzero if the function processes the 
message, and zero if it does not. 


Comments 


The dialog function is used only if the dialog class is used for the dialog 
box. This is the default class and is used if no explicit class is given in the 
dialog-box template. Although the dialog function 1s similar to a window 
function, it must not call the DefWindowProc function to process 
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unwanted messages. Unwanted messages are processed internally by the 
dialog-class window function. 


The dialog-function address, passed as the /pDialogFunc parameter, must 
be created by using the MakeProcInstance function. | 


HBITMAP CreateDiscardableBitmap(hDC, nWidth, nHeight) 


This function creates a discardable bitmap that is compatible with the 
device identified by the hDC parameter. The bitmap has the same number 
of color planes or bits-per-pixel format as the specified device. An applica- 
tion can select this bitmap as the current bitmap for a memory device that 
is compatible with the one specified by the hDC parameter. 


Parameter Type/ Description 

hDC HDC Identifies a device context. 

nWidth short Specifies the width (in bits) of the bitmap. 
nHeight short Specifies the height (in bits) of the bitmap. 


Return Value 


The return value identifies a bitmap if the function is successful. 


Otherwise, it is NULL. 


Comments 


Windows can discard a bitmap created by this function only if an applica- 
tion has not selected it into a display context. If Windows discards the bit- 
map when it is not selected and the application later attempts to select it, 
the SelectObject function will return zero. When this occurs, the applica- 
tion should remove the handle to the bitmap by using DeleteObject. 


HRGN CreateEllipticRgn(X/, Y1, X2, Y2) 


This function creates an elliptical region. 


Parameter Type/Definition 

XI short Specifies the 2-coordinate of the upper-left 
corner of the bounding rectangle of the ellipse. 

Y1 short Specifies the y-coordinate of the upper-left 


corner of the bounding rectangle of the ellipse. 


184 


CreateF ont 


X2 short Specifies the z-coordinate of the lower-right 
corner of the bounding rectangle of the ellipse. 


Y2 short Specifies the y-coordinate of the lower-right 
corner of the bounding rectangle of the ellipse. 


Return Value 


The return value identifies a new region if the function is successful. 


Otherwise, it is NULL. 


Comments 


The width of the rectangle, specified by the absolute value of X2 — X1, 
must not exceed 32,767 units. This limit also applies to the height of the 
rectangle. 


HRGN CreateEllipticRgnIndirect(/pRect) 


This function creates an elliptical region. 


Parameter Type/Description 


lpRect LPRECT Points toa RECT data structure that 
contains the coordinates of the upper-left and lower- 
right corners of the bounding rectangle of the ellipse. 


Return Value 


The return value identifies a new region if the function is successful. 
Otherwise, it is NULL. 


Comments 


The width of the rectangle must not exceed 32,767 units. This limit 
applies to the height of the rectangle as well. 


HFONT CreateFont(nHeighi, nWidth, nEscapement, nOrientation, 
nWeight, cltalic, cUnderline, cStrikeOut, cCharSet, 
cOutputPrecision, cClipPrecision, cQuality, 
cPitchAndFamily, lpFacename) 


This function creates a logical font that has the specified characteristics. 
The logical font can subsequently be selected as the font for any device. 
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Parameter Type/Description 


nHeight short Specifies the desired height (in logical units) of 
the font. The font height can be specified in three ways: 
If nHeight is greater than zero, it is transformed into 
device units and matched against the cell height of the 
available fonts. If it is zero, a reasonable default size is 
used. If it is less than zero, it is transformed into device 
units and the absolute value is matched against the 
character height of the available fonts. For all height 
comparisons, the font mapper looks for the largest font 
that does not exceed the requested size, and, if there is 
no such font, looks for the smallest font available. 


nWidth short Specifies the average width (in logical units) of 
characters in the font. If n Width is zero, the aspect ratio 
of the device will be matched against the digitization 
aspect ratio of the available fonts to find the closest 
renee determined by the absolute value of the dif- 
erence. 


nEscapement short Specifies the angle (in tenths of degrees) of each 
line of text written in the font (relative to the bottom of 
the page). 

nOrientation short Specifies the angle (in tenths of degrees) of each 
character’s baseline (relative to the bottom of the page). 


nWetght short Specifies the desired weight of the font in the 
range 0 to 1000 (for example, 400 is normal, 700 is bold). 
If nWeitght is zero, a default weight is used. 


cltalic BYTE § Specifies whether the font is italic. 

cUnderline BYTE Specifies whether the font is underlined. 

cStrikeOut BYTE Specifies whether characters in the font are 
struck out. 

cCharSet BYTE Specifies the desired character set. The follow- 


ing values are predefined: 


ANSI_ CHARSET 
OEM_ CHARSET 


Others may be obtained from a specific font’s manufac- 
turer. 
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cClipPrecision 


cQuality 


cPitchAndFamily 
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BYTE Specifies the desired output precision. The 
output precision defines how closely the output must 
match the requested font’s height, width, character 
orientation, escapement, and pitch. It can be any one 
of the following values: 


OUT_ CHARACTER. PRECIS 
OUT_ DEFAULT_ PRECIS 
OUT_STRING_ PRECIS 
OUT_ STROKE. PRECIS 


BYTE Specifies the desired clipping precision. The 
clipping precision defines how to clip characters that are 
partially outside the clipping region. It can be any one of 
the following values: 


CLIP_ CHARACTER_ PRECIS 
CLIP_ DEFAULT _ PRECIS 
CLIP_ STROKE. PRECIS 


BYTE Specifies the desired output quality. The out- 
put quality defines how carefully GDI must attempt to 
match the logical-font attributes to those of an actual 

physical font. It can be any one of the following values: 


DEFAULT_ QUALITY 
DRAFT_ QUALITY 
PROOF_ QUALITY 


BYTE Specifies the pitch and family of the font. The 
two low-order bits specify the pitch of the font and can 
be any one of the following values: 


DEFAULT_ PITCH 
FIXED_ PITCH 
VARIABLE_ PITCH 


The four high-order bits of the field specify the font 
family and can be any one of the following values: 


FF_ DECORATIVE 
FF_ DONTCARE 
FF_ MODERN 

FF_ ROMAN 

FF_ SCRIPT 
FP_SWISS 
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loFacename LPSTR Points to a null-terminated character string 
that specifies the typeface name of the font. The length 
of this string must not exceed 30 characters. The 
EnumFonts function can be used to enumerate the 
typeface names of all currently available fonts. 


Return Value 


The return value identifies a logical font if the function is successful. 
Otherwise, it is NULL. 


Comments 


The CreateFont function does not create a new font. It merely selects the 
closest match from the fonts available in GDI’s pool of physical fonts. 


HFONT CreateFontIndirect(lpLogFont) 


This function creates a logical font that has the characteristics given in 
the data structure pointed to by the lpLogFoné parameter. The font can 
subsequently be selected as the current font for any device. 


Parameter Type/Description | 

lnLogFont LOGFONT FAR * Points toa LOGFONT data 
structure that defines the characteristics of the logical 
font, 


Return Value 


The return value identifies a logical font if the function is successful. 


Otherwise, it is NULL. 


Comments 


The CreateFontIndirect function creates a logical font that has all 

the specified characteristics. When the font is selected by using the 
SelectObject function, GDI’s font mapper attempts to match the logical 
font with an existing physical font. If it fails to find an exact font, 1t pro- 
vides an alternate whose characteristics match as many of the requested 
characteristics as possible. For a description of the font mapper, see 
Chapter 2, “Functions Overview.” 
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HBRUSH CreateHatchBrush(nJndez, rgbColor) 
This function creates a logical brush that has the specified hatched pat- 


tern and color. The brush can subsequently be selected as the current 
brush for any device. 


Parameter Type/Description 


nindex short Specifies the hatch style of the brush. It can be 
any one of the following values: 


Value Meaning 


HS— BDIAGONAL 45-degree upward hatch 
(left to right) 


HS— CROSS Horizontal and vertical 
crosshatch 
HS_ DIAGCROSS 45-degree crosshatch 


HS_ FDIAGONAL 45-degree downward hatch 
(left to right) 


HS. HORIZONTAL Horizontal hatch 
HS_ VERTICAL Vertical hatch 


rgbColor DWORD _ Specifies an RGB color value for the fore- 
ground color of the brush (the color of the hatches). 


Return Value 


The return value identifies a logical brush if the function is successful. 
Otherwise, it is NULL. 


HDC CreateIC(ipDriverName, IpDeviceName, |lpOutput, lpInitData) 
This function creates an information context for the specified device. The 


information context provides a fast way to get information about the 
device without creating a device context. 


Parameter Type/Description 
lnDriverName LPSTR Points to a null-terminated character string 


that specifies the DOS filename APSON). extension) of 
the device driver (for example, EPSON 
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lnDeviceName LPSTR Points toa null-terminated character string 
that specifies the name of the specific device to be 
supported (for example, EPSON FX-80). The 
inDeviceName parameter is used if the module sup- 
ports more than one device. 


lpOutput LPSTR Points to a null-terminated character string 
that specifies the DOS file or device name for the physi- 
cal output medium (file or port). 


lpInitData LPSTR Points to device-specific initialization data 
for the device driver. The lpInitData parameter must be 
NULL if the device driver is to use the default initializa- 
tion (if any) specified by the user through the control 
panel. 


Return Value 


The return value identifies an information context for the specified device 
if the function is successful. Otherwise, it is NULL. 


Comments 

DOS device names follow DOS conventions; an ending colon (:) is recom- 
mended, but optional. Windows strips the terminating colon so that a 
device name ending with a colon is mapped to the same port as the 
same name without a colon. 

The driver and port names must not contain leading or trailing spaces. 


GDI output functions cannot be used with information contexts. 


HMENU CreateMenu( ) 


This function creates a menu. The menu is initially empty, but can be 
filled with menu items by using the ChangeMenu function. 


This function has no parameters. 
Return Value 


The return value identifies the newly created menu. It is NULL if the menu 
cannot be created. - as 
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HANDLE CreateMetaFile(/pFilename) 


This function creates a metafile device context. 


Parameter Type/Description 


lpFilename LPSTR Points to a null-terminated character string 
that specifies the name of the metafile. If the IpFilename 
parameter is NULL, a device context for a memory 
metafile is returned. 


Return Value 


The return value identifies a metafile device context if the function is 
successful. Otherwise, it is NULL. 


HBRUSH CreatePatternBrush(hBitmap) 


This function creates a logical brush that has the pattern specified by 
the hBitmap parameter. The brush can subsequently be selected for any 
device that supports raster operations. For more information, see the 
RC_BITBLT raster capability in the GetDeviceCaps function, later 
in this chapter. 


Parameter Type/Description 


hBitmap HBITMAP Identifies the bitmap. It is assumed 
to have been created by using the CreateBitmap, 
CreateBitmapIndirect, LoadBitmap, or 
CreateCompatibleBitmap function. The min- 
imum size for a bitmap to be used in a fill pattern 
is 8 X 8. 


Return Value 


The return value identifies a logical brush if the function is successful. 


Otherwise, it is NULL 


Comments 
A pattern brush can be deleted without affecting the associated bitmap by 


using the DeleteObject function. This means the bitmap can be used to 
create any number of pattern brushes. 
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HPEN CreatePen(nPenStyle, nWidth, rgbColor) 
This function creates a logical pen having the specified style, width, and 


color. The pen can be subsequently selected as the current pen for any 
device. 


Parameter Type/Description 


nPenStyle short Specifies the pen style. [t can be any one of the 
following values: 


Value Pen Style: 


) Solid 

1 Dash 

2 Dot 

3 Dash-dot 

4 Dash-dot-dot 

5 Null 
nWidth short Specifies the width of the pen (in logical units). 
rgbColor DWORD Specifies an RGB color value that identifies 


the color of the pen. 


Return Value 


The return value identifies a logical pen if the function is successful. 
Otherwise, it is NULL. 


Comments 


Pens with a physical width greater than one pixel will always have either 
null or solid style. 
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HPEN CreatePenIndirect(lpLogPen) 


This function creates a logical pen that has the style, width, and color 
given in the data structure pointed to by the /pLogPen parameter. 


Parameter Type/Description 

lpLogPen LOGPEN FAR * Points to the LOGPEN data 
structure that contains information about the logical 
pen. 


Return Value 


The return value identifies a logical pen object if the function is successful. 
Otherwise, it is NULL. 


Comments 


Pens with a physical width greater than one pixel will always have either 
null or solid style. 


HRGN CreatePolygonRgn(lpPoints, nCount, nPolyFillMode) 


This function creates a polygonal region. 


Parameter Type/Description 


lpPoints LPPOINT Points to an array of POINT data struc- 
tures. Each point specifies the a and ycoordinates of 
one vertex of the polygon. | 


nCount short Specifies the number of points in the array. 


nPolyFillMode short Specifies the polygon-filling mode to be used 
for filling the region. It can be ALTERNATE or 
WINDING (for an explanation of these modes, see the 
SetPolyFillMode function, later in this chapter). 


Return Value 


The return value identifies a new region if the function is successful. 


Otherwise, it is NULL. 
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HRGN CreateRectRgn(X1, Y1, X2, Y2) 


This function creates a rectangular region. 


Parameter Type/Description 


X1 short Specifies the xcoordinate of the upper-left 
corner of the region. 


Y1 short Specifies the ycoordinate of the upper-left 
corner of the region. 


X2 short Specifies the a-coordinate of the lower-right 
corner of the region. 


Y2 short Specifies the ycoordinate of the lower-right 
corner of the region. 


Return Value 


The return value identifies a new region if the function is successful. 


Otherwise, it is NULL. 


Comments 
The width of the rectangle, specified by the absolute value of X2 — X1, 


must not exceed 32,767 units. This limit applies to the height of the 
rectangle as well. 


HRGN CreateRectRgnIndirect(ipRect) 


This function creates a rectangular region. 


Parameter Type/Description 
lpRect LPRECT Points toa RECT data structure that 


contains the coordinates of the upper-left and lower- 
right corners of the region. 


Return Value 


The return value identifies a new region if the function is successful. 


Otherwise, it is NULL. 
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Comments 


The width of the rectangle must not exceed 32,767 units. This limit 
applies to the height of the rectangle as well. 


HBRUSH CreateSolidBrush(rgbColor) 


This function creates a logical brush that has the specified solid color. The 
brush can subsequently be selected as the current brush for any device. 


Parameter Type/ Description 


rgoColor DWORD Specifies an RGB color value that identifies 
the color of the brush. 


Return Value 


The return value identifies a logical brush if the function is successful. 


Otherwise, it is NULL. 


HWND CreateWindow(IpClassName, lp WindowName, dwStyle, X, 
Y, nWidth, nHeight, hWndParent, hMenu, 
hInstance, lpParam) 


This function creates an overlapped, pop-up, or child window. The 
Create Window function specifies the window class, window title, win- 
dow style, and (optionally) initial position and size of the window. The 
aaa ae function also specifies the window’s parent (if any) 

and menu. 


For overlapped, pop-up, and child windows, the Create Window function 
sends WM_ CREATE, WM. GETMINMAXINFO, and WM... NCCREATE 
messages to the window. The WM_ CREATE message contains the value 
specified by the /pParam parameter. If WS. VISIBLE style is given, 
Create Window sends the window all the messages required to activate 
and show the window. 


If the window style specifies a title bar, the window title pointed to by 

the lp WindowName parameter is displayed in the title bar. When using 
CreateWindow to create controls such as buttons, check boxes, and text 
controls, the lp WindowName parameter specifies the text of the control. 
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Parameter Type/Description 


lnClassName LPSTR Points to a null-terminated character string 
that names the window class. The class name can be any 
name registered with the RegisterClass function or 
any of the predefined control-class names specified in 
Table 3.3. 


lpWindowName LPSTR Points to a null-terminated character string 
that represents the window name. 


dwStyle DWORD Specifies the style of window being created. 
It can be any combination of the styles given in Table 
3.4, the control styles given in Table 3.5, or a combina- 
tion of styles created by using the bitwise OR operator. 


xX int Specifies the initial zposition of the window. For 
an overlapped or pop-up window, the X parameter is the 
initial 2-coordinate of the window’s upper-left corner (in 
screen coordinates). If this value is CW_USEDEFAULT, 
Windows selects the default position for the window’s 
upper-left corner. For a child window, X is the 2coor- 
dinate of the upper-left corner of the window in the 
client area of its parent window. 


Y int Specifies the initial y position of the window. For 
an overlapped window, the Y parameter is the initial 
ycoordinate of the window’s upper-left corner. For a 
pop-up window, Yis the ycoordinate (in screen coordi- 
nates) of the upper-left corner of the pop-up window. 
For list-box controls, Y is the ycoordinate of the 
upper-left corner of the control’s client area. For a child 
window, Yis the ycoordinate of the upper-left corner of 
the child window. All of these coordinates are for the 
window, not the window’s client area. 


nWidth int Specifies the width (in device units) of the window. 
For overlapped windows, the nWidth parameter is 
either the window’s width (in screen coordinates) or 
CW. USEDEFAULT. If nWidth is CW. USEDEF AULT, 
Windows selects a default width and height for the 
window (the default width extends from the initial 
a-position to the right edge of the screen, and the 
default height extends from the initial y-position to 
the top of the icon area). 


nHeight int Specifies the height (in device units) of the win- 
dow. For overlapped windows, the nHezght parameter is 
the window’s height in screen coordinates. If the nWidth 
parameter is CW_ USEDEFAULT, Windows ignores 
nHeight. 
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hWndParent HWND _Identifies the parent window of the window 
being created. A valid window handle must be supplied 
when creating a child window. For pop-up windows, a 
handle can be supplied, but is not required. Overlapped 
windows must not have a parent window, so the 
hWndParent parameter must be set to NULL. 


hMenu HMENU Identifies a menu or a child-window 
identifier. The meaning depends on the window style. 
For overlapped or pop-up windows, the hMenu parame- 
ter identifies the menu to be used with the window. It 
can be NULL, if the class menu is to be used. For child 
windows, hMenu specifies the child-window identifier, an 
integer value. The child-window identifier is determined 
by the application and should be unique for all child 
windows with the same parent window. 


hInstance HANDLE _ Identifies the instance of the module to be 
associated with the window. 

lpParam LPSTR Points to a value that is passed to the 
window through the /Param parameter of the 
WM... CREATE message. 


Return Value 


The return value identifies the new window. It is NULL if the window is 
not created. 


Comments 


For overlapped windows where the X parameter is CW_ USEDEFAULT, 
the Y parameter can be one of the show-style parameters described with 
the Show Window function, or, for the first overlapped window to be 
created by the application, 1t can be the nC’mdShow parameter passed 
to the WinMain function. 


Table 3.3 lists the window control classes; Table 3.4 lists the window 
styles; Table 3.5 lists the control styles: 
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Table 3.3 


Control Classes 


Class 


BUTTON 


EDIT 


LISTBOX 


SCROLLBAR 


STATIC 


198 


Meaning 


Designates a small rectangular child window that represents 
a button the user can turn on or off by clicking it. Button 
controls can be used alone or in groups, and can either be 
labeled or appear without text. Button controls typically 
change appearance when the user clicks them. 


Designates a rectangular child window in which the user can 
enter text from the keyboard. The user selects the control, 
and gives it the input focus by clicking it or moving to it by 
using the TAB key. The user can enter text when the control 
displays a flashing caret. The mouse can be used to move the 
cursor and select characters to be replaced, or to position the 
cursor for inserting characters. The BACKSPACE key can be 
used to delete characters. 


Edit controls use the fixed-pitch font and display ANSI 
characters. They expand tab characters into as many space 
characters as are required to move the cursor to the next tab 
stop. Tab stops are assumed to be at every eighth character 
position. 


Designates a list of character strings. This control is used 
whenever an application needs to present a list of names, 
such as filenames, that the user can view and select. The 
user can select a string by pointing to it and clicking. When 
a string is selected, it is highlighted and a notification 
message is passed to the parent window. A scroll bar can 

be used with a list-box control to scroll lists that are too 
long or too wide for the control window. 


Designates a rectangle that contains a thumb and has | 
direction arrows at both ends. The scroll bar sends a noti- 
fication message to its parent window whenever the user 
clicks the control. The parent window is responsible for 
updating the thumb position, if necessary. Scroll-bar 
controls have the same appearance and function as scroll 
bars used in ordinary windows. Unlike scroll bars, scroll-bar 
controls can be positioned anywhere in a window and used 
whenever needed to provide scrolling input for a window. 


The scroll-bar class also includes size-box controls. A size- 
box control is a small rectangle that the user can expand to 
change the size of the window. 


Designates a simple text field, box, or rectangle that can be 
used to label, box, or separate other controls. Static controls 
take no input and provide no output. 


Table 3.4 
Window Styles 


Style 


WS_ BORDER 
Ws_ CAPTION 


WSs_ CHILD 
WSs. CHILDWINDOW 


WS... CLIPCHILDREN 


Ws_ CLIPSIBLINGS 


WS_ DISABLED 
WS_ DLGFRAME 


WS_ GROUP 


WS_ HSCROLL 


WS-_. ICONIC 


CreateWindow 


Meaning 


Creates a window that has a border. 


Creates a window that has a title bar (implies 
the WS_ BORDER style). 


Creates a child window. Cannot be used with 


the WS. POPUP style. 


Creates a child window that has the 
WS-_ CHILD style. 


Excludes the area occupied by child windows 
when drawing within the parent window. 
Used when creating the parent window. 


Clips child windows relative to each 

other; that is, when a particular child 
window receives a paint message, the 

Ws_ CLIPSIBLINGS style clips all other 
overlapped child windows out of the region 
of the child window to be updated. (If 

WS. CLIPSIBLINGS is not given and child 
windows overlap, it is possible, when drawing 
within the client area of a child window, to 
draw within the client area of a neighboring 
child window.) For use with the WS_ CHILD 
style only. 


Creates a window that is initially disabled. 


Creates a window with a double border but no 
title. | 


Specifies the first control of a group of controls 
in which the user can move from one control 
to the next by using the DIRECTION keys. All 
controls defined with the WS_ GROUP style 
after the first control belong to the same 
group. The next control with the WS. GROUP 
style ends the style group and starts the next 
group (that is, one group ends where the next 
begins). Only dialog boxes use this style. 


a a window that has a horizontal scroll 
ar. 


Creates a window that is initially iconic. For 


use with the WS_ OVERLAPPED style only. 
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Table 3.4 (continued) 
Style 


WS_ MAXIMIZE 

Ws_ MAXIMIZEBOX 

WS_ MINIMIZE 

WS_ MINIMIZEBOX 

WS_ OVERLAPPED 

WS_ OVERLAPPEDWINDOW 


WS_ POPUP 


WS_ POPUPWINDOW 


WS_ SYSMENU 
Ws. TABSTOP 


WS_ THICKFRAME 


WS_ VISIBLE 


Ws_ VSCROLL 
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Meaning 


Creates a window of maximum size. 
Creates a window that has a maximize box. 
Creates a window of minimum size. 
Creates a window that has a minimize box. 
Creates an overlapped window. 


Creates an overlapped window that has the 
WS. CAPTION, WS_ OVERLAPPED, 
WS... THICKFRAME, and 

WS. SYSMENU styles. 


Creates a pop-up window. Cannot be used 
with the WS_ CHILD style. 


Creates a pop-up window that has the 
WS... BORDER, WS_ POPUP, and 
WS_SYSMENU styles. 


Creates a window that has a system-menu box 
in its title bar. Used only for windows with 
title bars. If used with a child window, this 
style creates a close box instead of a system- 
menu box. 


Specifies one of any number of controls 
through which the user can move by using the 
TAB key. The TAB key moves the user to the 
next control specified by the WS_ TABSTOP 
style. Only dialog boxes use this style. 


Creates a window with a thick frame that can 
be used to size the window. 


Creates a window that is initially visible. This 
applies to overlapped and pop-up windows. 
For overlapped windows, the Y parameter is 
used as a Show Window function parameter. 


Creates a window that has a vertical scroll bar. 


Table 3.5 
Control Styles 


Style 
BUTTON Class 
BS_. AUTOCHECKBOX 


BS_ AUTORADIOBUTTON 
BS_ AUTO3STATE 

BS_ CHECKBOX 

BS_ DEFPUSHBUTTON 
BS_ GROUPBOX 

BS_ LEP TTEXT 
BS_.PUSHBUTTON 


BS_ RADIOBUTTON 


CreateWindow 


Meaning 


Identical to BS. CHECKBOX, except that the 
button automatically toggles its state whenever 
the user clicks it. 


Identical to BS- RADIOBUTTON, except that 
the button is checked, the application is notified 
by BN_ CLICKED, and the checkmarks are 
removed from all other radio buttons in the 
group. 

Identical to BS_ 3STATE, except that the button 
cera toggles its state when the user 

clicks it. 


Designates a small rectangular button that may 
be checked; its border is bold when the user clicks 
the button. Any text appears to the right of the 
button. 


Designates a small elliptical button with a bold 
border. This button represents the default user 
response. Any text is displayed within the button. 
Windows sends a message to the parent window 
when the user clicks the button. 


Designates a rectangle into which other buttons 
are grouped. Any text is displayed in the rect- 
angle’s upper-left corner. 


Causes text to appear on the left side of the radio 
button or check-box button. Use this style with 
the BS_ CHECKBOX, BS_ RADIOBUTTON, or 
BS_ 38STATE styles. 


Designates a small elliptical button that contains 
the given text. The control sends a message to 
its parent window whenever the user clicks the 
button. 


Designates a small circular button whose border 
becomes bold when the user clicks it. In addition, 
to make the border bold, Windows sends a 
message to the button’s parent window notifying 
it that a click occurred. On the next click, 
Windows makes the border normal again and 
sends another message. 
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Table 3.5 (continued) 


Style 


BS_ 3STATE 


BS_ USERBUTTON 


EDIT Class 
ES_ AUTOHSCROLL 


ES_ AUTOVSCROLL 


ES_ CENTER 
ES_LEFT 
ES_ MULTILINE 
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Meaning 


Identical to BS.. CHECKBOX, except that a button 
can be grayed as well as checked. The grayed state 

Paco | is used to show that a check box has been 
disabled. 


Designates a user-defined button. The parent 
window is notified when the button is clicked. 
Notification includes a request to paint, invert, and 
disable the button. 


Automatically scrolls text to the right by 10 char- 
acters when the user types a character at the end 
of the line. When the user presses the ENTER key, 
the control scrolls all text back to position zero. 


Automatically scrolls text up one page when the user 
presses the ENTER key on the last line. 


Centers text. 
Aligns text flush-left. 


Designates multiple-line edit control. (The default 

is single-line.) If the ES_ AUTOVSCROLL style is 
specified, the edit control shows as many lines as 
possible and scrolls vertically when the user presses 
the ENTER key. If ES. AUTOVSCROLL is not given, 
the edit control shows as many lines as possible and 
beeps if the ENTER key is pressed when no more lines 
can be displayed. 


If the ES. AUTOHSCROLL style is specified, the 
multiple-line edit control automatically scrolls 
horizontally when the caret goes past the right edge 
of the control. To start a new line, the user must 
press the ENTER key. If ES. AUTOHSCROLL is not 
given, the control automatically wraps words to 
the beginning of the next line when necessary; a 
new line is also started if the ENTER key is pressed. 
The position of the wordwrap is determined by 

the window size. If the window size changes, the 
wordwrap position changes, and the text is redis- 
played. 
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Table 3.5 (continued) 


Style 


ES_ NOHIDESEL 


ES_ RIGHT 


STATIC Class 


SS_ BLACKFRAME 
SS_ BLACKRECT 
SS_ CENTER 


SS_ GRAYFRAME 
SS. GRAYRECT 
SS_ ICON 


SS_ LEFT 


SS_ RIGHT 


Meaning 


Multiple-line edit controls can have scroll bars. An 
edit control with scroll bars processes its own scroll- 
bar messages. Edit controls without scroll bars scroll 
as described above, and process any scroll messages 
sent by the parent window. 


Normally, an edit control hides the selection when the 
control loses the input focus, and inverts the selection 
when the control receives the input focus. Specifying 


ES_ NOHIDESEL deletes this default action. 
Aligns text flush-right. 


Specifies a box with black frame. 
Specifies a black-filled rectangle. 


Designates a simple rectangle and displays the given 
text centered in the rectangle. The text is formatted 
before it is displayed. Words that would extend past 
the end of a line are automatically wrapped to the 
beginning of the next centered line. 


Specifies a box with gray frame. 
Specifies a gray-filled rectangle. 


Designates an icon displayed in the dialog box. The 
given text is the name of an icon (not a filename 
defined elsewhere in the resource file. For the ICON 
statement, the n Width and nfleight parameters in the 
Create Window function are ignored; the icon 
automatically sizes itself. 


Designates a simple rectangle and displays the given 
text flush-left in the rectangle. The text is formatted 
before it is displayed. Words that would extend past 
the end of a line are automatically wrapped to the 
beginning of the next flush-left line. 


Designates a simple rectangle and displays the given 
text flush-right in the rectangle. The text is formatted 
before it is displayed. Words that would extend past 
the end of a line are automatically wrapped to the 
beginning of the next flush-right line. 
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Table 3.5 (continued) 


Style 


Meaning 


SS_ SIMPLE 


SsS_ USERITEM 
SS_. WHITEFRAME 
SS. WHITERECT 


LISTBOX Class 
LBS_ MULTIPLESEL 


LBS_ NOREDRAW 


LBS_ NOTIFY 


LBS_ SORT 
LBS_ STANDARD 


SCROLLBAR Class 
SBS_ BOTTOMALIGN 


SBS_ HORZ 


SBS_ LEF'TALIGN 


204 


Designates a simple rectangle and displays a single 
line of text flush-left in the rectangle. The line of 
text cannot be shortened or altered in any way. 
(The control’s parent window or dialog box must 
not process the WM_CTLCOLOR message.) 


Specifies a user-defined item. 
Specifies a box with white frame. 
Specifies a white-filled rectangle. 


String selection is toggled each time the user clicks 
or double-clicks the string. Any number of strings 
can be selected. 


List-box display is not updated when changes are 
made. This style can be changed at any time by 
sending a WW. SETREDRAW message. 


Parent window receives an input message whenever 
the user clicks or double-clicks a string. 


Strings in the list box are sorted alphabetically. 


Strings in the list box are sorted alphabetically and 

the parent window receives an input message whenever 
the user clicks or double-clicks a string. The list box 
contains a vertical scroll bar and borders on all sides. 


Used with the SBS. HORZ style. The bottom edge of 
the scroll bar is aligned with the bottom edge of the 
rectangle specified by the X, Y, n Wedth, and nHeight 
parameters given in the Create Window function. The 
scroll bar has the default height for system scroll bars. 


Designates a horizontal scroll bar. If neither the 
SBS. BOTTOMALIGN nor SBS. TOPALIGN style is 
specified, the scroll bar has the height, width, and 
position given in the CreateWindow function. 


Used with the SBS_ VERT style. The left edge of the 
scroll bar is aligned with the left edge of the rectangle 
specified by the X, Y, nWidth, and nHeight parameters 
given in the Create Window function. The scroll bar 
has the default width for system scroll bars. 


Table 3.5 (continued) 
Style 


SBS_ RIGHTALIGN 


SBS_ SIZEBOX 


SBS_ SIZEBOXBOTTOMRIGHTALIGN 


SBS_ SIZEBOXTOPLEFTALIGN 


SBS_ TOPALIGN 


SBS_ VERT 


CreateWindow 


Meaning 


Used with the SBS_ VERT style. The 
right edge of the scroll bar is aligned 
with the right edge of the rectangle 
specified by the X, Y, nWidth, and 
nHeight parameters given in the 
Create Window function. The scroll 
bar has the default width for system 
scroll bars. | 


Designates a size box. If neither the 
SBS_ SIZEBOXBOTTOMRIGHTALIGN 
nor SBS_ SIZEBOXTOPLEF TALIGN 
style is specified, the size box has the 
height, width, and position given in 

the Create Window function. 


Used with the SBS_ SIZEBOX style. 
The lower-right corner of the size box 
is aligned with the lower-right corner 
of the rectangle specified by the X, Y, 
nWidth, and nHezght parameters given 
in the CreateWindow function. The 
size box has the default size for sys- 
tem size boxes. 


Used with the SBS_ SIZEBOX style. 
The upper-left corner of the size box is 
aligned with the upper-left corner of 
the rectangle specified by the X, Y, 
nWidth, and nHeight parameters given 
in the Create Window function. The 
size box has the default size for sys- 
tem size boxes. 


Used with the SBS_ HORZ style. The 
top edge of the scroll bar is aligned 
with the top edge of the rectangle 
specified by the X, Y, n Width, and 
nHeight parameters given in the 
Create Window function. The scroll 
bar has the default height for system 
scroll bars. 


Designates a vertical scroll bar. If 
neither the SBS_ RIGHTALIGN 
nor SBS. LEFTALIGN style is spec- 
ified, the scroll bar has the height, 
width, and position given in the 
Create Window function. 
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DWORD DefHookProc(code, wParam, lParam, lplpfnNextHook) 


This function calls the next function in a chain of hook functions. A 
hook function is a function that processes events before they are sent 
to an application’s message-processing loop in the WinMain function. 
When an application defines more than one hook function by using 
the Set WindowsHook function, Windows forms a linked list or hook 
chain. Windows places functions of the same‘type in a chain. 


Parameter Type/Description 


code int Specifies a code used by the Windows hook func- 
tion (also called the message filter function) to deter- 
mine how to process the message. 


wParam WORD Specifies the word parameter of the message 
that the hook function is processing. 


lParam : LONG Specifies the long parameter of the message 
that the hook function is processing. 


lonipfnNextHook FARPROC FAR * Points to a memory location 
that contains the FARPROC structure returned by 
the Set} WindowsHook function. Windows changes 
the value at this location after an application calls the 
Unhook WindowsHook function. 


Return Value 


The return value specifies a value that is directly related to the code 
parameter. 


long DefWindowProc(hWnd, wMsg, wParam, lParam) 


This function provides default processing for any Windows messages that 
a given application does not process. All window messages that are not 
explicitly processed by the class window function must be passed to the 
DefWindowProc function. 
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Parameter Type/Description 

hWnd HWND Identifies the window that passes the 
message. 

wMsg unsigned Specifies the message number. 

wParam WORD Specifies 16 bits of additional message- 
dependent information. 

lParam LONG § Specifies 32 bits of additional message- 


dependent information. 


Return Value 


The return value specifies the result of the message processing and 
depends on the actual message sent. 


ATOM DeleteAtom(nAtom) 


This function deletes an atom and, if the atom’s reference count is zero, 
removes the associated string from the atom table. 


An atom’s reference count specifies the number of times the atom has been 
added to the atom table. The AddAtom function increases the count on 
each call; the DeleteAtom function decreases the count on each call. 
DeleteAtom removes the string only if the atom’s reference count is zero. 


Parameter Type/Description 
nAtom ATOM Identifies the atom and character string to be 
| deleted. 


Return Value 
The return value specifies the outcome of the function. It is NULL if the 


function is successful. It is equal to the nAtom parameter if the function 
failed and the atom has not been deleted. 
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BOOL DeleteDO(hDC) 


This function deletes the specified device context. If the hDC parameter 
is the last device context for a given device, the device is notified and all 
storage and system resources used by the device are released. 


Parameter Type/Description 


ADC HDC Identifies the device context. 


Return Value 


The return value specifies whether the device context is deleted. It is non- 

zero if the device context is successfully deleted (regardless of whether the 
deleted device context is the last context for the device). If an error occurs, 
the return value is zero. 


BOOL DeleteMetaFile(hMF) 


This function deletes access to a metafile by freeing the system resources 
associated with that metafile. It does not destroy the metafile itself, but 
it invalidates the metafile handle, AMF. Access to the metafile can be 
ee by retrieving a new handle by using the GetMetaFile 
unction. 


Parameter Type/Description 


hMF HANDLE Identifies the metafile to be deleted. 


Return Value 
The return value specifies whether the metafile handle is invalidated. It 


is nonzero if the metafile’s system resources are deleted. It 1s zeroif the | 
hMF parameter is not a valid handle. 


BOOL DeleteObject(hObject) 
This function deletes a logical pen, brush, font, bitmap, or region from 


memory by freeing all system storage associated with the object. After 
the object is deleted, the hObject handle is no longer valid. 
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Parameter Type/Description 


hObject HANDLE Identifies a handle to a logical pen, brush, 


font, bitmap, or region. 


Return Value 
The return value specifies whether the specified object is deleted. It is non- 


zero if the object is deleted. It is zero if the hObject parameter is not a 
valid handle or is currently selected into a device context. 


Comments 


The object to be deleted should not be currently selected into a device con- 
text, unless the context is deleted before the object is deleted. 


When a pattern brush is deleted, the bitmap associated with the brush is 
not deleted. The bitmap must be deleted independently. 


void DestroyCaret( ) 

This function destroys the current system-caret shape, frees the caret from 
the window that currently owns it, and removes the caret from the screen 
if it is visible. The DestroyCaret function checks the ownership of the 
caret and destroys the caret only if a window in the current task owns it. 


If the system-caret shape was previously a bitmap, DestroyCaret does 
not free the bitmap. 


This function has no parameters. 

Return Value 

None | 

Comments | 

The system caret is a shared resource. If a window has created a caret 


shape, it destroys that shape before it loses the input focus or becomes 
inactive. 
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BOOL DestroyMenu(hMenu) 


This function destroys the menu specified by the hMenu parameter and 
frees any memory that the menu occupied. 


Parameter Type/Description 
hMenu HMENU Identifies the menu to be destroyed. 


Return Value 


The return value specifies whether or not the specified menu is destroyed. 
It is nonzero if the menu is destroyed. Otherwise, it is zero. 


BOOL Destroy Window(h Wnd) 


This function destroys the specified window. The Destroy Window func- 
tion hides or permanently closes the window, sending the appropriate mes- 
sages to the window to deactivate it and remove the input focus. It also 
destroys the window menu, flushes the application queue, destroys out- 
standing timers, removes clipboard ownership, and breaks the clipboard- 
viewer chain, if the window is at the top of the viewer chain. It sends 


WM. DESTROY and WM_ NCDESTROY messages to the window. 


If the given window is the parent of any windows, these child windows are 
automatically destroyed when the parent window Is destroyed. Destroy- 
Window destroys child windows first, and then the window itself. 


Destroy Window also destroys modeless dialog boxes created by the 
CreateDialog function. 


Parameter Type/Description 
hWnd HWND Identifies the window to be destroyed. 
Return Value 


The return value specifies whether or not the specified window is de- 
stroyed. It is nonzero if the window is destroyed. Otherwise, it 1s zero. 
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int DialogBox(hInstance, lp TemplateName, hWndParent, lpDialogFunc) 


This function creates a modal dialog box that has the size, style, and con- 
trols specified by the dialog-box template given by the lp TemplateName 
parameter. The hWndParent parameter identifies the application win- 
dow that owns the dialog box. The callback function pointed to by the 
ee unc parameter processes any messages received by the dia- 

og box. 


The DialogBox function does not return control until the callback func- 
tion terminates the modal dialog box by calling the EndDialog function. 


Parameter Type/Description 


hInstance HANDLE | Identifies an instance of the module whose 
executable file contains the dialog-box template. 


loTemplateName LPSTR Points to a character string that names 
the dialog-box template. The string must be a null- 
terminated character string. 


hWndParent HWND Identifies the window that owns the dialog 
box. 


lpDialogF'unc FARPROC Is the procedure-instance address of the 
dialog function. See the following “Comments” section 
for details. 


Return Value 


The return value specifies the value of the nResult parameter in the 
EndDialog function that is used to terminate the dialog box. Values 
returned by the application’s dialog box are processed by Windows and 
ee not returned to the application. The return value is —1 if the function 
ails. 


Comments 


The DialogBox function calls the GetDC function in order to obtain 
a display-context. Problems will result if all the display contexts in the 
Windows display-context cache have been retrieved by GetDC and 
DialogBox attempts to access another display context. 
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The callback function must use the Pascal calling convention and must 
be declared FAR. The callback function must have the following form: 


int FAR PASCAL DialogFunc(hWnd, wMsg, wParam, lParam) 
HWND hWnd; 

unsigned wMsq; 

WORD wParam; 

DWORD /Param; 


DialogF unc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Description 

hWnd Identifies the dialog box that receives the message. 

wMsg Specifies the message number. 

wParam Specifies 16 bits of additional message-dependent 
information. | 

[Param Specifies 32 bits of additional message-dependent 
information. 


Return Value 


The callback function should return nonzero if the function processes the 
message and zero if it does not. 


Comments 


Although the callback function is similar to a window function, 1t must 
not call the DefWindowProc function to process unwanted messages. 
Unwanted messages are processed internally by the dialog-class window 
function. 


The callback-function address, passed as the lpDialogF unc parameter, 
must be created by using the MakeProcInstance function. 


int DialogBoxIndirect(hInstance, hDTemplate, hWndParent, 
lpDialogFunc) 


This function creates an application’s modal dialog box that has the size, 


style, and controls specified by the dialog-box template associated with 
the hDTemplate parameter. The hWndParent parameter identifies the 
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application window that owns the dialog box. The callback function 
pointed to by [pDialogF'unc processes any messages received by the dia- 
log box. 


The DialogBoxIndirect function does not return control until the call- 
back function terminates the modal dialog box by calling the EndDialog 
function. 


Parameter Type/Description 


hInstance HANDLE Identifies an instance of the module whose 
executable file contains the dialog-box template. 


hDTemplate HANDLE _ Identifies the DLGTEMPLATE struc- 


ture. 


hWndParent HWND Identifies the window that owns the dialog 
box. 


lpDialogF'unc FARPROC Is the procedure-instance address of the 
dialog function. See the following “Comments” section 
for details. 


Return Value 


The return value specifies the value of the wResult parameter specified in 
the EndDialog function that is used to terminate the dialog box. Values 
returned by the application’s dialog box are processed by Windows and 
are not returned to the application. 


Comments 


The callback function must use the Pascal calling convention and be 
declared FAR. The callback function must have the following form: 


BOOL FAR PASCAL DialogFunc(hWnd, wMsg, wParam, lParam) 
HWND AWnd; 

unsigned wh{sq; 

WORD wParam; 

DWORD [Paran; 


DialogF'unc is a placeholder for the application-supplied function name. 


The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 
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Parameter Description 

hWnd Identifies the dialog box that receives the message. 

wMsqg Specifies the message number. 

wParam Specifies 16 bits of additional message-dependent a 
information. 

[Param Specifies 32 bits of additional message-dependent 
information. 


Return Value 


The callback function should return nonzero if the function processes the 
message and zero if it does not. 


Comments 


Although the callback function is similar to a window function, it must 
not call the DefWindowProc function to process unwanted messages. 
Unwanted messages are processed internally by the dialog-class window 
function. 


The callback-function address, passed as the [pDialogF unc parameter, 
must be created by using the MakeProcInstance function. 


LONG DispatchMessage(lpMsqg) 


This function passes the message in the MSG structure pointed to by the 
lpMsg parameter to the window function of the specified window. 


Parameter Type/Description 

lpMsg LPMSG Points to an MSG data structure that con- 
tains message information from the Windows applica- 
tion queue. 


The structure must contain valid message values. If 
IpMsg points to a WM_ TIMER message and the /Param 
parameter of the WM_ TIMER message is not NULL, 
then the lParam parameter is the address of a function 
that is called instead of the window function. 
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Return Value 


The return value specifies the value returned by the window function. 
Its meaning depends on the message being dispatched, but generally the 
return value is ignored. 


int DigDirList(hDlg, lnPathSpec, nIDListBox, nIDStaticPath, wFiletype) 


This function fills a list-box control with a file or directory listing. It fills 
the list box specified by the nJDListBor parameter with the names of all 
files matching the pathname given by the [pPathSpec parameter. 


The DigDirList function shows subdirectories enclosed in square brackets 
({]), and shows drives in the form |[—a—], where zis the drive letter. 


The /pPathSpec parameter has the following form: 
[dreves]|]\ | directory|\ directory]...\ | [filename] 


In this example, drive is a drive letter, directory is a valid directory name, 
and filename is a valid filename that may contain wildcard characters. The 
wildcard characters are a question mark (?), meaning “match any charac- 
ter,” and an asterisk (*), meaning “match any number of characters.” 


If the lpPathSpec parameter includes a drive and/or directory name, the 
current drive and directory are changed to the designated drive and 
directory before the list box is filled. The text control identified by the 
nlDStaticPath parameter is also updated with the new drive and/or direc- 
tory hame. 


After the list box is filled, lpPathSpec is updated by removing the drive 
and/or directory portion of the pathname. 


DigDirList sends LB-RESETCONTENT and LB. DIR messages to the 


list box. 


Parameter Type/Description 

hDig HWND Identifies the dialog box that contains 
the list box. 

lpPathSpec LPSTR Points to a pathname string. The string 


must be a null-terminated character string. 
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nIDListBox int Specifies the identifier of a list-box control. If 
nlDListBozx is zero, DigDirList assumes that no list 
box exists and does not attempt to fill if. 


niDStaticPath int Specifies the identifier of the static-text con- 
trol used for displaying the current drive and direc- 
tory. If nIDStaticPath is zero, DigDirList assumes 
that no such text control is present. 


wFiletype unsigned Specifies DOS file attributes of the files 
to be displayed. It can be any combination of the 
values given in Table 3.6. Values can be combined 
by using the bitwise OR operator. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if a 
listing was made, even an empty listing. A zero return value implies that 
the input string did not contain a valid search path. 


Table 3.6 

DOS File Attributes 

Attribute Value 

(Hexadecimal) Meaning 

0000 Read/write data files with no 
additional attributes 

0001 Read-only files 

0002 Hidden files 

0004 System files 

0010 Subdirectories 

0020 Archives 

2000 LB_DIR flags 

4000 Drives 

8000 Exclusive bit** 


+ If the LB_ DIR flag is set, Windows places the messages 
generated by DlgDirList in the application’s queue; otherwise 
they are sent directly to the dialog function. 


+* If the exclusive bit is set, only files of the specified type are 
listed. Otherwise, files of the specified type are listed in addition 
to normal files. 
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BOOL DlgDirSelect(hDlg, lpString, nIDListBoz) 


This function retrieves the current selection from a list box. It assumes 
that the list box has been filled by the DigDirList function and that the 
selection is a drive letter, a file, or a directory name. 


The DlgDirSelect function copies the selection to the buffer given by the 
lpString parameter. If the current selection is a directory name or drive 
letter, DigDirSelect removes the enclosing square brackets (and hyphens, 
for drive letters) so that the name or letter is ready to be inserted into a 
new pathname. 


DigDirSelect sends LB. GETCURSEL and LB. GETTEXT messages to 
the list box. 


Parameter Type/Description 

hDlg HWND Identifies the dialog box that contains the 
list box. 

lpString LPSTR Points to a buffer that is to receive the 
selected pathname. 

nlIDListBox int Specifies the integer ID of a list-box control in the 
dialog box. 


Return Value 


The return value specifies the status of the current list-box selection. It is 
nonzero if the current selection is a directory name. Otherwise, it is zero. 


Comments 


The DlgDirSelect function does not allow more than one filename to be 
returned from a list box. 


The list box must not be a multiple-selection list box. If it is, this function 
will not return a zero value and lpString will remain unchanged. 


BOOL DPtoLP(hDC, IlpPoints, nCount) 


This function converts device points into logical points. The function 
maps the coordinates of each point specified by the I[pPoints parameter 
from the device coordinate system into GDI’s logical coordinate system. 
The conversion depends on the current mapping mode and the settings 
of the origins and extents for the device’s window and viewport. 
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Parameter ~ Type/Description 

hDC HDC Identifies the device context. 

lpPoints LPPOINT Points to an array of points. Each point 
must be a POINT data structure. 

nCount short Specifies the number of points in the array. 

Return Value 


The return value specifies whether the conversion has taken place. It is 
nonzero if all points are converted. Otherwise, it is zero. 


BOOL Drawlcon(hDC, X, Y, hlcon) 


This function draws an icon on the specified device. The DrawlIcon func- 
tion places the icon’s upper-left corner at the location specified by the X 
and Y parameters. The location is subject to the current mapping mode of 
the device context. 


Parameter Type/ Description 

ADC HDC Identifies the device context for a window. 

X int Specifies the logical 2-coordinate of the upper-left 
corner of the icon. 

Y int Specifies the logical ycoordinate of the upper-left 
corner of the icon. 

hIcon HICON Identifies the icon to be drawn. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
function is successful. Otherwise, it is zero. 


Comments 
The icon resource must have been previously loaded by using the 


LoadIcon function. The MM TEXT mapping mode must be selected 
prior to using this function. 
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void DrawMenuBar(hWna) 


This function redraws the menu bar. If a menu bar is changed after Win- 
dows has created the window, this function should be called to draw the 
changed menu bar. 


Parameter Type/Description 
hWnd HWND Identifies the window whose menu needs 
redrawing. 


Return Value 


None 


int DrawText(hDC, lpString, nCount, lpRect, wFormat) 


This function draws formatted text in the rectangle specified by the IpRect 
parameter. It formats text by expanding tabs into appropriate spaces, 
justifying text to the left, right, or center of the given rectangle, and 
breaking text into lines that fit within the given rectangle. The type of 
formatting is specified by the wFormat parameter. 


The DrawText function uses the device context’s selected font, text 
color, and background color to draw the text. Unless the DT_ NOCLIP 
format is used, DrawText clips the text so that the text does not appear 
outside the given rectangle. All formatting is assumed to have multiple 


lines unless the DT_ SINGLELINE format is given. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

lnString LPSTR Points to the string to be drawn. If the 
nCount parameter is —1, the string must be null- 
terminated. 

nCount int Specifies the number of bytes in the string. If 


nCount is —1, then lpString is assumed to be a long 
pointer to a null-terminated string and DrawText 
computes the character count automatically. 


lnRect LPRECT Points toa RECT data structure that 
contains the rectangle (in logical coordinates) in which 
the text is to be formatted. 


wFormat WORD Specifies the method of formatting the text. 
It can be a combination of the values given in Table 3.7. 
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Return Value 


The return value specifies the height of the text. 


Comments 


If the selected font is too large for the specified rectangle, the DrawText 
function does not attempt to substitute a smaller font. 


Table 3.7 lists the values for the wf ormat parameter. These values 
can be combined by using the bitwise OR operator. Note that the 
DT CALCRECT, DT_ EXTERNALLEADING, DT_INTERNAL, 
DT NOCLIP, and DT. NOPREFIX values cannot be used with the 
DT TABSTOP value: 


Table 3.7 

DrawText Formats 

Value Meaning 

DT_ BOTTOM Specifies bottom-justified text (single line only). 
DT CALCRECT Determines the width and height of the rectangle. 


If there are multiple lines of text, DrawText will 
use the width of the rectangle pointed to by the 
lpRect parameter and extend the base of the 
rectangle to bound the last line of text. If there 

is only one line of text, DrawText will modify 
the right side of the rectangle so that it bounds 
the last character in the line. In either case, 
DrawText returns the height of the formatted 


text. 
DT_ CENTER Centers text. 
DT_ EXPANDTABS Expands tab characters. The default number of 


characters per tab is eight. 


DT_ EXTERNALLEADING Includes the font external leading in line height. 
Normally, external leading is not included in the 
height of a line of text. 


DT_ LEFT Aligns text flush-left. 


DT_ NOCLIP Draws without clipping. DrawText is somewhat 
faster when DT. NOCLIP is used. 
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Table 3.7 (continued) 


Value 
DT_ NOPREFIX 


DT_ RIGHT 
DT_ SINGLELINE 


DT_ TABSTOP 


DT. TOP 
DT_ VCENTER 
DT_ WORDBREAK 


Meaning 


Turns off processing of prefix characters. 
Normally, Draw Text interprets the mnemonic- 
prefix character “&” as a directive to underscore 
the character that follows, and the mnemonic- 
prefix characters “&&” as a directive to print a 
single “&”. By specifying DT. NOPREF'IX, this 
processing is turned off. 

Aligns text flush-right. 

Specifies single line only. Carriage returns and 
linefeeds do not break the line. 


Sets tab stops. The high-order byte of the 

wl ormat parameter is the number of characters 
for each tab. The default number of characters 
per tab is eight. 


Specifies top-justified text (single line only). 


Specifies vertically centered text (single line only). 
Specifies word breaking. Lines are automatically 


broken between words if a word would extend 
past the edge of the rectangle specified by the 
lpRect parameter. Pressing the ENTER key also 
causes a line break. 
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BOOL Ellipse(hDC, X1, Y1, X2, Y2) 


This function draws an ellipse. The center of the ellipse is the center of the 
bounding rectangle specified by the X1, Yi, X2, and Y2 parameters. The 
ellipse border is drawn with the current pen, and the interior is filled with 
the current brush. 


If the bounding rectangle is empty, nothing is drawn. 


Parameter Type/Description 
hDC HDC | Identifies the device context. 
X1 short Specifies the logical z-coordinate of the upper- 


left corner of the bounding rectangle. 


Y1 short Specifies the logical y-coordinate of the upper- 
left corner of the bounding rectangle. 


X2 short Specifies the logical z-coordinate of the lower- 
right corner of the bounding rectangle. 


Y2 short Specifies the logical y-coordinate of the lower- 
right corner of the bounding rectangle. 


Return Value 


The return value specifies whether the ellipse is drawn. It is nonzero if the 
ellipse is drawn. Otherwise, it is zero. 


Comments 

The width of the rectangle, specified by the absolute value of X2 — X12, 
must not exceed 32,767 units. This limit applies to the height of the 
rectangle as well. 


The current position is neither used nor updated by this function. 


BOOL EmptyClipboard( ) 

This function empties the clipboard and frees handles to data in the clip- 
board. It then assigns ownership of the clipboard to the window that 
currently has the clipboard open. 


This function has no parameters. 
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Return Value 


The return value specifies the status of the clipboard. It is nonzero if the 
clipboard is emptied. It is zero if an error occurs. 


Comments 


The clipboard must be open when the EmptyClipboard function is 
called. 


~BOOL EnableHardwarelnput(fEnable/nput) 


This function disables mouse and keyboard input. The input is saved if the 
fEnableInput parameter is TRUE and discarded if it is FALSE. 


Parameter Type/Description 


fEnableInput BOOL Specifies that the function should save input if 
the fEnablelnput parameter is set to a nonzero value; 
specifies that the function should discard input if the 
fEnableInput parameter is set to zero. 


Return Value 
The return value specifies whether mouse and keyboard input is disabled. 


It is nonzero if input was previously enabled. Otherwise, it is zero. The 
default return value is nonzero (TRUE). 


BOOL EnableMenultem(hMenu, wlDEnableltem, wEnable) 


This function enables, disables, or grays a menu item. 


Parameter Type/Description 


hMenu HMENU | Specifies the menu. 


wlDEnable[tem ‘WORD Specifies the menu item to be checked. The 
wlDEnableltem parameter can specify pop-up menu 
items as well as menu items. 
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wEnable WORD Specifies the action to take. It can be a 
combination of MF_ DISABLED, MF_ ENABLED, 
or MF. GRAYED, with MF_ BYCOMMAND or 
MF_BYPOSITION. These values can be combined 
by using the bitwise OR operator. These values 
have the following meanings: 


Value Meaning 
MF_ BYCOMMAND Specifies that the 


wlDEnableltem parameter 

ives the menu item ID 
MF. BYCOMMAND is 
the default ID). 


MF... BYPOSITION Specifies that the 
wlDEnableltem parameter 
gives the position of the 
menu item (the first item 
is at position zero). 


MF_ DISABLED Menu item is disabled. 
MF. ENABLED Menu item is enabled. 
MF_ GRAYED Menu item is grayed. 


Return Value 


The return value specifies the previous state of the menu item. 


Comments 


To disable or enable input to a menu bar, see the WM_SYSCOMMAND 


message. 


BOOL EnableWindow(hWnd, bEnable) 


This function enables or disables mouse and keyboard input to the 
specified window or control. When input is disabled, input such as mouse 
clicks and key presses are ignored by the window. When input is enabled, 
all input is processed. 


The Enable Window function enables mouse and keyboard input to a 


window if the bEnable parameter is nonzero, and disables it if b&-nable is 
Zero. 
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Parameter Type/Description 

hWnd HWND Identifies the window to be enabled or 
disabled. | 

bEnable BOOL Specifies whether the given window is to 
be enabled or disabled. 


Return Value 


The return value specifies the outcome of the function. It 1s nonzero if the 
window is enabled or disabled as specified. It is zero if an error occurs. 


Comments 


A window must be enabled before it can be activated. For example, if 
an application is displaying a modeless dialog box and has disabled its 
main window, the main window must be enabled before the dialog box 
is destroyed. Otherwise, another window will get the input focus and 
be activated. 


If a child window is disabled, it is ignored when Windows tries to deter- 
mine which window should get mouse messages. 


Initially, all windows are enabled by default. EnableWindow must be 
used to disable a window explicitly. 


void EndDialog(hDlg, nResult) 


This function terminates a modal dialog box and returns the given result 
to the DialogBox function that created the dialog box. The EndDialog 
function is required to complete processing whenever the DialogBox func- 
tion is used to create a modal dialog box. The function must be used in the 
dialog function of the modal dialog box and should not be used for any 
other purpose. 


The dialog function can call EndDialog at any time, even during the 
processing of the WM_INITDIALOG message. If called during the 
WM_ INITDIALOG message, the dialog box is terminated before it is 
shown or before the input focus is set. 


EndDialog does not terminate the dialog box immediately. Instead, it 
sets a flag that directs the dialog box to terminate as soon as the dialog 
function ends. The EndDialog function returns to the dialog function, 
so the dialog function must return control to Windows. 
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Parameter Type/Description 

hDig HWND Identifies the dialog box to be destroyed. 

nhesult int Specifies the value to be returned from 
the dialog box to the DialogBox function that a 
created it. 


Return Value 


None 


void EndPaint(hWnd, lpPaint) 


This function marks the end of painting in the given window. The 
EndPaint function is required for each call to the BeginPaint func- 
tion, but only after painting is complete. 


Parameter Type/Description 


hWnd HWND Identifies the window that is repainted. 
lpPaint LPPAINTSTRUCT Points toa PAINTSTRUCT 


data structure that contains the painting information 
retrieved by the BeginPaint function. 


Return Value 


None 


Comments 


If the caret was hidden by the BeginPaint function, EndPaint restores 
the caret to the screen. 


BOOL EnumChildWindows(hWndParent, lpEnumF unc, lParam) 


This function enumerates the child windows that belong to the specified 

parent window by passing the handle of each child window, in turn, to 

the application-supplied callback function pointed to by the [pEnumF unc 

parameter. — 


The EnumChildWindows function continues to enumerate windows 


until the called function returns zero or until the last child window has 
been enumerated. 
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Parameter Type/ Description 


hWndParent HWND Identifies the parent window whose child 
windows are to be enumerated. 


loEnumF unc FARPROC Is the procedure-instance address of the 
callback function. 


(Param LONG Specifies the value to be passed to the call- 
back function for the application’s use. 


Return Value 


The return value specifies nonzero if all child windows have been 
enumerated. Otherwise, it 1s zero. 


Comments 


This function does not enumerate pop-up windows that belong to the 
hWndParent parameter. 


The address passed as the lpEnumF unc parameter must be created by 
using the MakeProcInstance function. 


The callback function must use the Pascal calling convention and must 
be declared FAR. The callback function must have the following form: 


BOOL FAR PASCAL EnumFunc( hWnd, lParam) 
HWND hWnd; 
LONG [Param; 


EnumF unc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Description 
hWnd Identifies the window handle 
lParam Specifies the long parameter argument of the 


EnumChildWindows function. 


Return Value 


The callback function should return a nonzero value to continue enumera- 
tion; it should return zero to stop enumeration. 
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WORD EnumClipboardFormats(wFormat) 


This function enumerates the formats found in a list of available formats 
that belong to the clipboard. On each call to this function, the wFormat 
parameter specifies a known available format, and the function returns the 
format that appears next in the list. The first format in the list can be 
retrieved by setting wk ormat to zero. 


Parameter Type/Description 


wFormat WORD Specifies a known format. 


Return Value 


The return value specifies the next known clipboard data format. It is zero 
if wFormat specifies the last format in the list of available formats. 


Comments 


Before it enumerates the formats by using EnumClipboardFormats, 
an application must open the clipboard by using OpenClipboard. 


short EnumFonts(hDC, lpFacename, lpFontFunc, lpData) 


This function enumerates the fonts available on a given device. For each 
font having the typeface name specified by the /pF'acename parameter, the 
EnumFonts function retrieves information about that font and passes it 
to the function pointed to by the IpFontFunc parameter. The application- 
supplied callback function can process the font information as desired. 
Enumeration continues until there are no more fonts or the callback func- 
tion returns zero. | 


Parameter Type/ Description 
hDC HDC Identifies the device context. 
lpnFacename LPSTR Points to a null-terminated character string 


that specifies the typeface name of the desired fonts. If 
lpFacename is NULL, EnumFonts randomly selects and 
enumerates one font of each available typeface. 


loFontFunc FARPROC Is the procedure-instance address of the 
callback function. See the following “Comments” section 
for details. 


lpData LPSTR Points to the application-supplied data. The 
data is passed to the callback function along with the 
font information. 
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Return Value 


The return value specifies the last value returned by the callback function. 
Its meaning is user-defined. 


Comments 


The address passed as the lpFontF'unc parameter must be created by using 
the MakeProcInstance function. 


The callback function must use the Pascal calling convention and must be 
declared FAR. The callback function must have the following form: 


short FAR PASCAL FontFunc(lpLogFont, lp TextMetrics, Font Type, lpData) 
LPLOGFONT IpLogFont; 

LPTEXTMETRICS IpTeztMetrics; 

short Font Type; 

LPSTR lpDaia; 


FontFunc is a placeholder for the application-supplied function name. The 
actual name must be exported by including it in an EXPORTS state- 
ment in the application’s module-definition file. 


Parameter Description 


lpLogFont Points toa LOGFONT data structure that contains 
information about the logical attributes of the font. 


ly TextMetrics Points to a TEXTMETRIC data structure that con- 
tains information about the physical attributes of the 


font. 

FontType Specifies the type of the font. 

lpData Points to the application-supplied data passed by 
EnumFonts. 


Return Value 


The return value can be any integer. 


Comments 


The AND operator can be used with the RASTER. FONTTYPE 
and DEVICE. FONTTYPE constants to determine the font type. The 
RASTER. FONTTYPE bit of the FontType parameter specifies whether 


the font is a raster or vector font. If the bit is one, the font is a raster font; 
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if zero, it is a vector font. The DEVICE_ FONTTYPE bit of Font Type 
specifies whether the font is a device- or GDI-based font. If the bit is one, 
the font is a device-based font; if zero, it is a GDI-based font. 


If the device is capable of text transformations (scaling, italicizing, and so 
on) only the base font will be enumerated. The user must inquire into the 
device’s text-transformation abilities to determine which additional fonts 
are available directly from the device. GDI can simulate the bold, italic, 
underlined, and strikeout attributes for any GDI-based font. 


EnumFonts only enumerates fonts from the GDI internal table. This does 
not include fonts that are generated by a device, such as fonts that are 
transformations of fonts from the internal table. The GetDeviceCaps 
function can be used to determine which transformations a device can per- 
form. This information is available by using the TEXTCAPS index. 


GDI can scale GDI-based raster fonts by one to five horizontally and one 
to eight vertically, unless PROOF_ QUALITY is being used. 


BOOL EnumMetaFile(hDC, hMF, IpCallbackFunc, IpClientData) 


This function enumerates the GDI calls within the metafile identified by 
the hMF parameter. The EnumMetaFile function retrieves each GDI 
call within the metafile and passes it to the function pointed to by the 
lnCallbackFunc parameter. This callback function, an application-supplied 
function, can process each GDI call as desired. Enumeration continues 
until there are no more GDI calls or the callback function returns zero. 


Parameter Type/ Description 

hDC HDC Identifies the device context associated with the 
metafile. 

hMF LOCALHANDLE Identifies the metafile. 


lnCallbackFunc FARPROC Is the procedure-instance callback func- 


tion. See the following “Comments” section for details. 
loClientData BYTE FAR * Points to the callback-function data. 
Return Value 
The return value specifies the outcome of the function. It is nonzero if the 


callback function enumerates all the GDI calls in a metafile; otherwise, it 
returns ZeTo. 
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Comments 


The callback function must use the Pascal calling convention and must be 
declared FAR. The callback function must have the following form: 


int FAR PASCAL EnumFunc(hDC, lpHTable, lpMFR, nObj, lpClientData) 
HDC ADC; 

LPHANDLETABLE I/pHTable; 

LPMETARECORD I[pMFR; 

int nObj; 

BYTE FAR * l[pClientData; 


EnumF unc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Description 

hDC Identifies the special device context that contains the 
metafile. 

lnHTable Points to a table of handles associated with the objects 
(pens, brushes, and so on) in the metafile. 

lpbMFR Points to a metafile record contained in the metafile. 

nObj Specifies the number of objects with associated handles 


in the handle table. 
lpChientData Points to the application-supplied data. 


Return Value 


The function can carry out any desired task. It must return a nonzero 
value to continue enumeration, or a zero value to stop it. 


short EnumObjects(hDO, nObjectType, lpObjectFunc, lpData) 


This function enumerates the pens and brushes available on a device. For 
each object that belongs to the given style, the callback function is called 
with the information for that object. The callback function is called until 
there are no more objects or the callback function returns zero. 
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Parameter Type/Description 


hDC HDC Identifies the device context. 


nObject Type short Specifies the object type. It can be one of the 
following values: 


OBJ_ BRUSH 
OBJ_ PEN 


lnObjectF'unc FARPROC Is the procedure-instance address of the 
application-supplied callback function. See the following 
“Comments” section for details. 


lpData LPSTR Points to the application-supplied data. The 
data is passed to the callback function along with the 
object information. 


Return Value 


The return value specifies the last value returned by the callback function. 
Its meaning is user-defined. 


Comments 


The address passed as the IpObjectF'unc parameter must be created by 
using the MakeProcInstance function. 


The callback function must use the Pascal calling convention and must be 
declared FAR. The callback function must have the following form: 


short FAR PASCAL ObjectFunc(lpLogObject, lpData) 
char FAR * [pLogObject; 
char FAR * [pData; | 


ObjectFunc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Description 


lnLogObject Points to a LOGPEN or LOGBRUSH data structure 
that contains information about the logical attributes of 
the object. 


loData Points to the application-supplied data passed to 
Enum Objects. 
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int EnumProps(hWnd, lpEnumFunc) 


This function enumerates all entries in the property list of the specified 
window. It enumerates the entries by passing them, one by one, to the call- 
back function specified by lpEnumF unc. EnumProps continues until the 
last entry is enumerated or the callback function returns zero. 


Parameter Type/Description 


hWnd HWND _ Identifies the window whose property list is 
to be enumerated. 


lpbEnumF une FARPROC Is the procedure-instance address of the 
callback function. See the following “Comments” section 
for details. 


Return Value 


The return value specifies the last value returned by the callback function. 


Comments 


The address passed in the lpEnumF unc parameter must be created by 
using the MakeProcInstance function. 


Fized Data Segments. The callback function must use the Pascal call- 
ing convention and must be declared FAR. In applications and dynamic 
libraries with fixed data segments and in dynamic libraries with movable 
data segments that do not contain a stack, the callback function must 
have the following form: 


int FAR PASCAL EnumFunc(hWnd, lpString, hData) 
HWND hWnd; 

LPSTR lpString; 

HANDLE hData; 


EnumF unc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Description 

hWnd Identifies a handle to the window that contains the 
property list. 

lnString Points to the null-terminated character string associated 
with the data handle. 

hData Identifies the data handle. 
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Return Value 


The callback function can carry out any desired task. It must return a 
nonzero value to continue enumeration, or a zero value to stop it. 


Comments 


Movable Data Segments. The callback function must use the Pascal calling 
convention and must be declared FAR. In applications with movable data 
segments and in dynamic libraries whose movable data segments also con- 
tain a stack, the callback function must have the following form: 


int FAR PASCAL EnumFunc(hWnd, nDummy, pString, hData) 
HWND hWnd; 

WORD nDummy; 

PSTR pString; 

HANDLE hData; 


EnumFunc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Description 

hWnd Identifies a handle to the window that contains the 
property list. 

nDummy Specifies a dummy parameter. 

pString Points to the null-terminated character string associated 
with the data handle. 

hData Identifies the data handle. 


Return Value 


The callback function can carry out any desired task. It should return a 
nonzero value to continue enumeration, or a zero value to stop it. 


Comments 


The alternate form above is required since movement of the data will 
invalidate any long pointer to a variable on the stack, such as the [pString 
parameter. The data segment typically moves if the callback function 
allocates more space in the local heap than is currently available. 
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BOOL EnumTaskWindows(h Task, lpEnumFunc, lParam) 


This function enumerates all windows associated with the h Task param- 
eter, which is returned by the GetCurrentTask function. (A task is 
any program that executes as an independent unit. All applications are 
executed as tasks and each instance of an application is a task.) The 
enumeration terminates when the callback function, pointed to by 


lpbEnumF une, returns FALSE. 
Parameter Type/Description 


hTask HANDLE Identifies a handle to the specified task. 


loEnumFunction FARPROC Is the procedure-instance address of the 
window’s callback function. 


lParam LONG § Specifies the 32-bit value that contains addi- 
tional parameters that are sent to the callback function 
pointed to by lpEnumF unc. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if all 
the windows associated with a particular task are enumerated. Otherwise, 
it is zero. 


Comments 


The callback function must use the Pascal calling convention and must be 
declared FAR. The callback function must have the following form: 


BOOL EnumFunc(hWnd, lParam) 
HWND hWnd; 
LONG [Param 


EnumFunc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Description 
hWnd Identifies a window associated with the current task. 
lParam Specifies the same argument that was passed to the 


Enum Task Windows function. 
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Return Value 


The callback function can carry out any desired task. It must return a 
nonzero value to continue enumeration, or a zero value to stop it. 


BOOL EnumWindows(lpEnumFunc, lParam) 


This function enumerates the windows on the screen by passing the han- 
dle of each window, in turn, to the callback function pointed to by the 
lpEnumFunc parameter. Child windows are not enumerated. 


The EnumWindows function continues to enumerate windows until the 
called function returns zero or until the last window has been enumerated. 


Parameter Type/ Description 


lpEnumFunce FARPROC Is the procedure-instance address of the 
callback function. See the following “Comments” sec- 
tion for details. 


lParam LONG Specifies the value to be passed to the call- 
back function for the application’s use. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if all 
windows have been enumerated. Otherwise, it is zero. 


Comments 


The address passed as the lpEnumFunc parameter must be created by 
using the MakeProcInstance function. 


The callback function must use the Pascal calling convention and must be 
declared FAR. The callback function must have the following form: 


BOOL EnumFunc(hWnd, (Param) 
HWND hWnd; 
LONG /[Param; 


EnumFunc is a placeholder for the application-supplied function name. 


The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 
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Parameter Description 
hWnd Identifies the window handle. 
[Param Specifies the long parameter argument of the 


Enum Windows function. 


Return Value 


The function must return a nonzero value to continue enumeration, or 
zero to stop lt. 


BOOL EqualRect(lpRect1, lpRect2) 


This function determines whether two rectangles are equal by comparing 
the coordinates of their upper-left and lower-right corners. If the values of 
these coordinates are equal, EqualRect returns a nonzero value; other- 
wise, it returns zero. 


Parameter Type/Description 


lpRect1 LPRECT Points toa RECT data structure that 
contains the upper-left and lower-right corner coordi- 
nates of the first rectangle. 


lpRect2 LPRECT Points toa RECT data structure that 
contains the upper-left and lower-right corner coordi- 
nates of the second rectangle. 


Return Value 


The return value specifies whether the specified rectangles are equal. It is 
nonzero if the two rectangles are identical; otherwise, it is zero. 


BOOL EqualRgn(hSrcRgn1, hSrcRgn2) 


This function checks the two given regions to determine whether they are 
identical. 


Parameter Type/Description 
hSrcRgnt HRGN Identifies a region. 
hSrcRgn2 HRGN Identifies a region. 
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Return Value 


The return value specifies whether the specified regions are equal. It is 
nonzero if the two regions are equal. Otherwise, it 1s zero. 


short Escape(hDC, nE scape, nCount, IpInData, lpOutData) 


This function allows applications to access facilities of a particular device 
that are not directly available through GDI. Escape calls made by an 
application are translated and sent to the device driver. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


nEscape short Specifies the escape function to be performed. 
| For a complete list of escape functions, see Appendix C, 
“Printer Escapes.” 


nCount short Specifies the number of bytes of data pointed to 
by the /p/nData parameter. 

lnInData LPSTR Points to the input data structure required 
for this escape. 

lpOutData LPSTR Points to the data structure to receive out- 


put from this escape. The /pOutData parameter should 
be NULL if no data are returned. 


Return Value 


The return value specifies the outcome of the function. It 1s positive if the 
function is successful (or is implemented, for the QUERYESCSUPPORT 
escape). The return value is zero if the escape is not implemented. A nega- 
tive value indicates an error. 


short EscapeCommFunction(nCid, nFunc) 
This function directs the communication device specified by the nCid 


parameter to carry out the extended function specified by the nF'unc 
parameter. 
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Parameter Type/Description 
nCid int Specifies the communication device to carry out 
the extended function. 


nFunc int Specifies the function code of the extended func- 
tion. It can be any one of the following values: 


Value Description 

CLRDTR Clears the data-terminal-ready 
(DTR) signal. 

CLRRTS Clears the request-to-send (RTS) 
signal. 

RESETDEV Resets the device if possible. 

SETDTR Sends the data-terminal-ready 
(DTR) signal. 

SETRTS Sends the request-to-send (RTS) 
signal. 

SETXOFF Causes transmission to act as if 
an XOFF character has been 
received. 

SETXON Causes transmission to act as if 
an XON character has been 
received. 


Return Value 
The return value specifies the result of the function. It is zero if it is suc- 


cessful. It is negative if the nFunc parameter does not specify a valid 
function code. 


short ExcludeClipRect(hDC, X1, Y1, X2, Y2) 


This function creates a new clipping region that consists of the existing 
clipping region minus the specified rectangle. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
X1 short Specifies the logical z-coordinate of the upper- 


left corner of the rectangle. 
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Y1 short Specifies the logical y-coordinate of the upper- 
left corner of the rectangle. 


X2 short Specifies the logical x-coordinate of the lower- 
right corner of the rectangle. 


Y2 short Specifies the logical y-coordinate of the lower- 
right corner of the rectangle. 


Return Value 


The return value specifies the new clipping region’s type. It is a short- 
integer value, and can be any one of the following values: 
COMPLEXREGION The region has overlapping borders. 

ERROR No region was created. 

NULLREGION The region is empty. 

SIMPLEREGION The region has no overlapping borders. 


Comments 
The width of the rectangle, specified by the absolute value of X2 — X1 


must not exceed 32,767 units. This limit applies to the height of the 
rectangle as well. 


short ExcludeUpdateRgn(hDC, hWnd) 


This function prevents drawing within invalid areas of a window by 
excluding an updated region in the window from a clipping region. 


Parameter Type/Description 

hDC HANDLE Identifies the device context associated 
with the clipping region. 

hWnd HWND _ Identifies the window being updated. 
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Return Value 


This value specifies the type of resultant region. It is a short-integer value, 
and can be any one of the following values: 

COMPLEXREGION The region has overlapping borders. 

ERROR No region was created. 

NULLREGION The region is empty. 

SIMPLEREGION The region has no overlapping borders. 


BOOL ExtTextOut(hDC, X, Y, wOptions, lpRect, lpString, nCount, lpDz) 


This function writes a character string, within a rectangular region on the 
specified display, using the currently selected font. The rectangular region 
can be opaque (filled with the current background color) and it can be a 
clipping region. A clipping region is the only region in a window to which 
output may be sent. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

xX short Specifies the logical x-coordinate of the origin of | 
the character cell for the first character in the specified 
string. 

Y short Specifies the logical y-coordinate of the origin of 
the character cell for the first character in the specified 
string. 

wOptions WORD Specifies the rectangle type. It can be one or 


both of the following values: 


ETO_ CLIPPED 
ETO_ OPAQUE 


The ETO_ CLIPPED value specifies that Windows will 
clip text to the rectangle. The ETO_ OPAQUE value 
specifies that the current background color fills the 
rectangle. 


loRect LPRECT Points toa RECT data structure. 
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lpString LPSTR Points to the specified character string. 
nCount short Specifies the number of characters in the string. 
loDz LPINT Points to an array of values that indicate the 


distance between origins of adjacent character cells. For 
instance, /pDz|i| logical units will separate the origins of 
character cell 2 and character cell 2+ 1. 


Return Value 


The return value specifies whether or not the string is drawn. It is nonzero 
if the string is drawn. Otherwise, it is zero. 


Comments 

If IpDxz is NULL, the function uses the default spacing between characters. 
The character-cell origins and the contents of the array pointed to by the 
loDz parameter are given in logical units. A character-cell origin is defined 
as the upper-left corner of the character cell. 


The current position is not used or updated by this function. 


242 


FillRect 


void FatalExit( Code) 
This function displays the current state of Windows and prompts for 
instructions on how to proceed. The display includes an error code, the 


Code parameter, followed by a symbolic stack trace, showing the flow of 
execution up to the point of call. 


Parameter Type/Description 
Code int Specifies the error code to be displayed. 


Return Value 


None 


Comments 


The FatalExit function prompts the user to respond to an “Abort, Break 
or Ignore” message. FatalE-xit processes the response as follows: 
A (Abort) Terminates Windows. 


B (Break) Simulates a non-maskable interrupt (NMI) to enter 
the debugger. 


I (Ignore) Returns to the caller. 
The FatalExit function is for debugging only. 
This function should be called whenever Windows detects a fatal error. All 


input and output is received and transmitted through the computer’s aux- 
iliary port (AUX). 


int FillRect(hDC, lpRect, hBrush) 
This function fills a given rectangle by using the specified brush. The 


FillRect function fills the complete rectangle, including the left and 
top borders, but does not fill the right and bottom borders. 


Parameter Type/Description 


hDC HDC Identifies the device context. 

lyRect LPRECT Points toa RECT data structure that con- 
tains the logical coordinates of the rectangle to be filled. 

hBrush cr ai Identifies the brush used to fill the rect- 
angle. 
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Return Value 


Although the FillRect function return type is an integer, the return value 
is not used and has no meaning. 


Comments 


The brush must have been created previously by using the Create- 
HatchBrush, CreatePatternBrush, or CreateSolidBrush function. 


When filling the specified rectangle, the FillRect function does not 
include the rectangle’s right and bottom sides. GDI fills a rectangle up 
to, but does not include, the right column and bottom row. 


FillRect compares the values of the top, bottom, left, and right fields 


of the specified rectangle. If bottom is less than or equal to top, or if 
right is less than or equal to left, the rectangle is not drawn. 


BOOL FillRgn(hDC, hRgn, hBrush) 


This function fills the region specified by the hRgn parameter with the 
brush specified by the hBrush parameter. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

hRgn HRGN Identifies the region to be filled. The region is 
assumed to have logical coordinates. 

hBrush HBRUSH Identifies the brush to be used to fill the 
region. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
function is successful. Otherwise, it is zero. 


ATOM FindAtom(IpString) 
This function searches the atom table for the character string pointed to 


by the lpString parameter and retrieves the atom associated with that 
string. 
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Parameter Type/Description 


lpString  LPSTR Points to the character string to be searched 
for. The string must be null-terminated. 


Return Value 


The return value identifies the atom associated with the given string. It is 
NULL if the string is not in the table. 


HANDLE FindResource(hInstance, lpName, lp Type) 


This function determines the location of a resource in the specified 
resource file. The lpName and lp Type parameters define the resource 
name and type, respectively. 


Parameter Type/Description 


hInstance HANDLE Identifies the instance of the module whose 
executable file contains the resource. 


lp Name LPSTR Points to a null-terminated character string 
that represents the name of the resource. 


lp Type LPSTR Points to a null-terminated character string 
that represents the type name of the resource. For 
predefined resource types, the lp Type parameter should 
be one of the following values: 


Value Meaning 

RT ACCELERATOR Accelerator table 

RT_ BITMAP Bitmap resource 

RT CURSOR Cursor resource 

RT DIALOG Dialog box 

RT_ FONT Font resource 

RT_ FONTDIR Font directory resource 

RT_ICON Icon resource 

RT MENU Menu resource 

RT_RCDATA User-defined resource 
(raw data) 

RT_ STRING String resource 
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Return Value 


The return value identifies the named resource. It is NULL if the requested 
resource cannot be found. 


Comments 


If the high-order word of the /pName or lp Type parameter is zero, the 
low-order word specifies the integer ID of the name or type of the given 
resource. Otherwise, the parameters are long pointers to null-terminated 
character strings. If the first character of the string is a pound sign (#), 
the remaining characters represent a decimal number that specifies the 
integer ID of the resource’s name or type. For example, the string #258 
represents the integer ID 258. 


To reduce the amount of memory required for the resources used by an 
application, the application should refer to the resources by integer ID 
instead of by name. ; 


HWND FindWindow(IpClassName, lp WindowName) 


This function returns the handle of the window whose class Is given by the 
lpClassName parameter and whose window name, or caption, is given by 
the lp WindowName parameter. 


Parameter Type/Description 


lpClassName LPSTR Points to a null-terminated character string 
that specifies the window’s class name. If lpClassName 
is NULL, all class names match. 


lpWindowName LPSTR Points toa null-terminated character string 
that specifies the window name (the window’s text cap- 
tion). If lp WindowName is NULL, all window names 
match. 


Return Value 


The return value identifies the window that has the specified class name 
and window name. It is NULL if no such window 1s found. 
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BOOL FlashWindow(hWnd, bInvert) 


This function “flashes” the given window once. Flashing a window means 
changing the appearance of its caption bar as if the window were chang- 
ing from inactive to active status, or vice versa. (An inactive caption bar 
changes to an active caption bar; an active caption bar changes to an inac- 
tive caption bar.) 


Typically, a window is flashed to inform the user that the window requires 
attention, but that it does not currently have the input focus. 


Parameter Type/Description 

hWnd HWND Identifies the window to be flashed. The win- 
dow can be either open or iconic. 

bInvert BOOL Specifies whether the window 1s to be flashed 


or returned to its original state. The window is flashed 
from one state to the other if the blnvert parameter is 

nonzero. If the b/nvert parameter is zero, the window is 
returned to its original state (either active or inactive). 


Return Value 


The return value specifies the window’s state before call to the Flash- 
Window function. It is nonzero if the window was active before the call. 
Otherwise, it is zero. 


Comments 


The Flash Window function flashes the window only once; for successive 
flashing, the application should create a system timer. 


The b/nvert parameter should be zero only when the window is getting the 
input focus and will no longer be flashing; it should be nonzero on succes- 
sive calls while waiting to get the input focus. 


This function always returns a nonzero value for iconic windows. If the 
window is iconic, FlashWindow will simply flash the icon; bInvert is 
ignored for iconic windows. 


BOOL FloodFill(hDC, X, Y, rgbColor) 


This function fills an area of the display surface with the current brush. 
The area is assumed to be bounded as specified by the rgbColor param- 
eter. The FloodF ill function begins at the point specified by the X and Y 
parameters and continues in all directions to the color boundary. 
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Parameter Type/ Description 

hDC HDC Identifies the device context. 

xX short Specifies the logical z-coordinate of the point 
where filling begins. 

Y short Specifies the logical ycoordinate of the point 
where filling begins. 

rgbColor DWORD _ Specifies an RGB color value that specifies 


the color of the boundary. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
function is successful. It is zero if the filling could not be completed, the 
given point already has the boundary color specified by rgbColor, or the 
point is outside the clipping region. 


Comments 
Not all devices support the FloodFill function. For more information, see 


the RC. BITBLT raster capability in the GetDeviceCaps function, later 
in this chapter. 


short FlushComm(nCid, nQueue) 
This function flushes all characters from the transmit or receive queue of 


the communication device specified by the nCid parameter. The nQueue 
parameter specifies which queue is to be flushed. 


Parameter Type/Description 


nCid int Specifies the communication device to be flushed. 

nQueue int Specifies the queue to be flushed. If nQueue is zero, 
the transmit queue is flushed. If it is 1, the receive queue 
is flushed. 


Return Value 
The return value specifies the result of the function. It is zero if it is suc- 


cessful. It is negative if nC?d is not a valid device, or if nQueue is not a 
valid queue. 
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int FrameRect(hDC, IpRect, hBrush) 


This function draws a border around the rectangle specified by the lpRect 
parameter. The FrameRect function uses the given brush to draw the 
border. The width and height of the border is always one logical unit. 


Parameter Type/Description 
hDC HDC Identifies the device context of the window. 
lpRect LPRECT Points toa RECT data structure that 


contains the logical coordinates of the upper-left 
and lower-right corners of the rectangle. 


hBrush HBRUSH Identifies the brush to be used for framing 
the rectangle. 


Return Value 


Although the return value type is integer, its contents should be ignored. 


Comments 


The brush identified by the hBrush parameter must have been created pre- 
viously by using the CreateHatchBrush, CreatePatternBrush, or 
CreateSolidBrush function. 


If the bottom field is less than or equal to the top field, or if right is less 
than or equal to left, the rectangle is not drawn. 


BOOL FrameRgn(hDO, hRgn, hBrush, nWidth, nHeight) 


This function draws a border around the region specified by the hRgn 
parameter, using the brush specified by the hBrush parameter. The nWidth 
parameter specifies the width of the border in vertical brush strokes; the 
nHeight parameter specifies the height in horizontal brush strokes. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

hRgn HANDLE Identifies the region to be enclosed in a 
border. The region is assumed to have logical coordi- 
nates. 

hBrush HBRUSH = Identifies the brush to be used to draw the 
border. 
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nWidth short Specifies the width in vertical brush strokes 
(in logical units). 
nieight short Specifies the height in horizontal brush strokes 


(in logical units). 
Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
function is successful. Otherwise, it 1s zero. 


HANDLE FreeLibrary(hLibModule) 
This function decreases the reference count of the loaded library module 


by one. When the reference count reaches zero, the memory occupied by 
the module is freed. 


Parameter Type/Description 


hLibModule HANDLE Identifies the loaded library module. 


Return Value 


The return value is unknown and undefined. 


void FreeProcInstance(/pProc) 


This function frees the function specified by the /pProc parameter from the 
data segment bound to it by the MakeProcInstance function. 


Parameter Type/Description 
lpProc FARPROC Is the procedure-instance address of the 


function to be freed. It must have been created previ- 
ously by using the MakeProcInstance function. 


Return Value 
None 
Comments 


After freeing a procedure instance, attempts to call the function using the 
freed procedure-instance address will result in an unrecoverable error. 
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BOOL FreeResource(hResData) 


This function removes a loaded resource from memory by freeing the allo- | 
cated memory occupied by that resource. 


The FreeResource function does not actually free the resource until the 
reference count is zero (that is, the number of calls to the function equals 
the number of times the application called the LoadResource function 
for this resource). This ensures that the data remain in memory for the 
application to use. 


Parameter Type/Description 


hResData HANDLE Identifies the data associated with the 
resource. The handle is assumed to have been created 
by using the LoadResource function. 


Return Value 
The return value specifies the outcome of the function. The return value is 


nonzero if the function has failed and the resource has not been freed. The 
return value is zero if the function is successful. 
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HWND GetActiveWindow( ) 


This function retrieves the window handle of the active window. The 
active window is either the window that has the current input focus, or 
the window explicitly made active by the SetActive Window function. 


This function has no parameters. 


Return Value 


The return value identifies the active window. 


DWORD GetAspectRatioF ilter(hDC) 


This function retrieves the setting for the current aspect-ratio filter. The 
aspect ratio is the ratio formed by a device’s pixel width and height. Infor- 
mation about a device’s aspect ratio is used in the creation, selection, and 
displaying of fonts. Windows provides a special filter, the aspect-ratio 
filter, to select fonts designed for a particular aspect ratio from all of 

the available fonts. The filter uses the aspect ratio specified by the 
SetMapperF lags function. 


Parameter Type/ Description 


ADC HDC Identifies the device context that contains the 
specfied aspect ratio. 


Return Value 


The return value specifies the aspect ratio used by the current aspect-ratio 
filter. The 2coordinate of the aspect ratio is contained in the high-order 
word, and the y coordinate is contained in the low-order word. 


int GetAsyncKeyState(vKey) 


This function determines whether a key is up or down, and whether the 

key was pressed after a previous call to the GetAsyncKeyState function. 

If the most significant bit of the return value is set, the key is currently 

down; if the least significant bit is set, the key was ‘pressed after a previous 

call to the function. oe 
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Parameter Type/Description 
vK ey int Specifies one of 256 possible virtual-keycode 
values. 


Return Value 
The return value specifies whether the key was pressed since the last call 
to GetAsyncKeyState and whether the key is currently up or down. If 


the most significant bit is set, the key is down, and if the least significant 
bit is set, the key was pressed after a preceding GetAsyncKeyState call. 


HMEM GetAtomHandle(wAtom) 


This function retrieves a handle (relative to the local heap) of the string 
that corresponds to the atom specified by the wAtom parameter. 


Parameter Type/ Description 


wAtom WORD Specifies an unsigned integer that identifies 
the atom whose handle is to be retrieved. 


Return Value 


The return value identifies the given atom’s string. It is zero if no such 
atom exists. 


WORD GetAtomName(nAtom, IpBuffer, nSize) 


This function retrieves a copy of the character string associated with the 
nAtom parameter and places it in the buffer pointed to by the lpBuffer 
parameter. The nSize parameter specifies the maximum size of the buffer. 


Parameter Type/Description 
nAtom ATOM Identifies the character string to be retrieved. 
loBuffer LPSTR Points to the buffer that is to receive the 


character string. 


nSize int Specifies the maximum size fin bytes) of the buffer. 
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Return Value 


The return value specifies the actual number of bytes copied to the buffer. 
It is zero if the specified atom is not valid. 


long GetBitmapBits(hBitmap, dwCount, IpBits) 


This function copies the bits of the specified bitmap into the buffer that 
is pointed to by the [pBits parameter. The dwCount parameter specifies 
the number of bytes to be copied to the buffer. The GetObject function 
should be used to determine the correct dwCount value for the given 
bitmap. 


Parameter Type/Description 

hBitmap HBITMAP Identifies the bitmap. 

dwCount long Specifies the number of bytes to be copied. 
lpBits LPSTR Points to the buffer that is to receive the 


bitmap. The bitmap is an array of short integers. 


Return Value - 


The return value specifies the actual number of bytes in the bitmap. It 
is zero if there is an error. 


DWORD GetBitmapDimension(hBitmap) 
This function returns the width and height of the bitmap specified by the 


hBitmap parameter. The height and width is assumed to have been set pre- 
viously by using the SetBitmapDimension function. 


Parameter Type/Description 


hBitmap HBITMAP Identifies the bitmap. 


Return Value 


The return value specifies the width and height of the bitmap, measured in 
tenths of millimeters. The height is in the high-order word, and the width 

is in the low-order word. If the bitmap width and height have not been set 
by using SetBitmapDimension, the return value is zero. 
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DWORD GetBkColor(hDC) 


This function returns the current background color of the specified device. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


Return Value 


The return value specifies an RGB color value that names the current 
background color. 


short GetBkMode(hDC) 
This function returns the background mode of the specified device. The 


background mode is used with text, hatched brushes, and pen style that 1s 
not a solid line. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


Return Value 


The return value specifies the current background mode. It can be 


OPAQUE or TRANSPARENT. 


DWORD GetBrushOrg(hDC) 


This function retrieves the current brush origin for the given device 
context. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

Return Value 

The return value specifies the current origin of the brush. The 2-coordinate 


is in the low word, and the ycoordinate is in the high word. The coordi- 
nates are assumed to be in device units. 
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Comments 


The initial brush origin is at the coordinate (0,0). 


BYTE GetBValue(rgbColor) 


This function extracts the blue value from an RGB color value. 


Parameter Type/Description 


rgbColor long Specifies a red, a green, and a blue color field, 
each specifying the intensity of the given color. 


Return Value 


The return value specifies a byte that contains the blue value of the 
rgbColor parameter. 


Comments 


The value OFFH corresponds to the maximum intensity value for a single 
byte; OOOH corresponds to the minimum intensity value for a single byte. 


HWND GetCapture( ) 

This function retrieves a handle that identifies the window that has the 
mouse capture. Only one window has the mouse capture at any given time; 
this window receives mouse input whether or not the mouse cursor is 
within its borders. 


This function has no parameters. 


Return Value 


The return value identifies the window that has the mouse capture; it is 
NULL if no window has the mouse capture. 


Comments 


A window receives the mouse capture when its handle is passed as the 
hWnd parameter of the SetCapture function. 
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WORD GetCaretBlinkTime{( ) 


This function retrieves the caret blink rate. The blink rate is the elapsed 
time in milliseconds between flashes of the system caret. 


This function has no parameters. 


Return Value 


The return value specifies the blink rate (in milliseconds). 


void GetCaretPos(lpPoint) 
This function retrieves the caret’s current position (in screen coordinates), 


and copies them to the POINT structure pointed to by the lpPoint 
parameter. 


Parameter Type/Description 


lpPownt LPPOINT Points to the POINT structure that is to 
receive the screen coordinates of the caret. 


Return Value 


None 


Comments 


The caret position is always given in the client coordinates of the window 
that contains the caret. 


BOOL GetCharWidth(hDC, wFirstChar, wLastChar, lpBuffer) 


This function retrieves the widths of individual characters in a consecutive 
group of characters from the current font. For example, if the wktrstChar 
parameter identifies the letter a and the wLastChar parameter identifies 
the letter z, the GetChar Width function retrieves the widths of all 
lowercase characters. The function stores the values in the buffer pointed 
to by the lpBuffer parameter. 
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Parameter Type/Description 

ADC HDC Identifies the device context. 

wk irstChar WORD Specifies the first character in a consecutive 
group of characters in the current font. 

wLastChar WORD Specifies the last character in a consecutive 
group of characters in the current font. 

lpBuffer LPINT Points to a buffer that will receive the width 


values for a consecutive group of characters in the 
current font. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
function is successful. Otherwise, it 1s zero. 


Comments 


If a character in the consecutive group of characters does not exist 1n a 
articular font, it will be assigned the width value of the default character 
which is usually the blank character). 


LONG GetClassLong(hWnd, nIndez) 


This function retrieves the long value specified by the n/ndex parameter 
from the WNDCLASS structure of the window specified by the hWnd 


parameter. 


Parameter Type/ Description 
hWnd HWND Identifies the window. 


nindex int Specifies the long value to be retrieved. It must be 
, one of the following values: 


Value Meaning 


GCL-_MENUNAME Retrieves a long pointer to the 


menu hame. 


GCL..WNDPROC _ Retrieves a long pointer to the 
window function. 
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Return Value 


The return value specifies the value retrieved from the WNDCLASS 
structure. 


Comments 


To access any extra four-byte values allocated when the window-class 
structure was created, use positive offsets as indexes, starting at zero for 
the first four-byte value in the extra space. 


int GetClassName(hWnd, IpClassName, nMaxCount) 


This function retrieves the class name of the window specified by the 
hWnd parameter. 


Parameter Type/Description 


hWnd HWND _ Identifies the window whose class name is 
to be retrieved. 


lpClassName LPSTR Points to the buffer that is to receive the 
class name. 


nMaxCount int Specifies the maximum number of bytes to be 
stored in the lpClassName parameter. If the actual 
name is longer, a truncated name ts copied to the 


buffer. 


Return Value 
The return value specifies the number of characters actually copied to 


lnClassName. The return value is zero if the specified class name Is not 
valid. 


WORD GetClassWord(hWnd, nIndez) 
This function retrieves the word that is that is specified by the nJndez 


parameter from the WNDCLASS structure of the window specified by 
the hWnd parameter. 


259 


GetClassWord 


Parameter Type/Description 
hWnd HWND Identifies the window. 
nindex int Specifies the word to be retrieved. It must be one 


of the following values: 
Value Meaning 


GCWW CBCLSEXTRA Retrieves two bytes of addi- 
tional window-class informa- 
tion. 


GCW.. CBWNDEXTRA _ Retrieves two bytes of addi- 
tional window information. 


GCW_ HBRBACKGROUND 
Retrieves a handle to the 
background brush. 


GCW_ HCURSOR Retrieves a handle to the 
cursor. 

GCW_ HICON Retrieves a handles to the 
icon. 

GCW. HMODULE Retrieves a handle to the 
module. 

GCW_ STYLE Retrieves the window-class 
style bits. 


Return Value 


The return value specifies the value retrieved from the WNDCLASS 
structure. 


Comments 
To access any extra two-byte values that were allocated when the window 


class structure was created, use positive offsets as indexes, starting at zero 
for the first two-byte value of the extra space. 


void GetClientRect(h Wnd, lpRect) 
This function copies the client coordinates of a window’s client area into 


the data structure pointed to by the [pRect parameter. The client coordi- 
nates specify the upper-left and lower-right corners of the client area. 
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Since client coordinates are relative to the upper-left corners of a window’s 
client area, the coordinates of the upper-left corner are (0,0). 


Parameter Type/Description 


hWnd HWND Identifies the window associated with the 
client area. 
lpRect LPRECT Points toa RECT data structure. 


Return Value 


None 


HANDLE GetClipboardData(wFormat) 


This function retrieves data from the clipboard in the format given by the 
wk ormat parameter. The clipboard must have been opened previously. 


Parameter Type/Description 


wk ormat WORD Specifies a data format. For a description of 
the data formats, see the SetClipboardData function, 
later in this chapter. 


Return Value 


The return value identifies the memory block that contains the data from 
the clipboard. It is NULL if there is an error. 


Comments 


The available formats can be enumerated in advance by using the 
EnumClipboardFormats function. 


The data handle returned by GetClipboardData is controlled by the 
clipboard, not by the application. The application should copy the data 
immediately, instead of relying on the data handle for long-term use. The 
application should not free the data handle or leave it locked. 
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int GetClipboardFormatName(wlormat, lpFormatName, nMaxCount) 


This function retrieves from the clipboard the name of the registered for- 
mat specified by the wFormat parameter. The name is copied to the buffer 
pointed to by the /pFormatName parameter. 


Parameter Type/ Description 

wk ormat WORD Specifies the type of format to be retrieved. 
It must not specify any of the predefined clipboard 
formats. 


lpFormatName LPSTR_ Points to the buffer that is to receive the 
format name. 


nMazCount int Specifies the maximum length (in bytes) of the 
string to be copied to the buffer. If the actual name is 
longer, it is truncated. 


Return Value 
The return value specifies the actual length of the string copied to the 


buffer. It is zero if the requested format does not exist or is a predefined 
format. 


HWND GetClipboardOwner{ ) 


This function retrieves the window handle of the current owner of the 
clipboard. 


This function has no parameters. 
Return Value 


The return value identifies the window that owns the clipboard. It is 
NULL if the clipboard is not owned. 


Comments 


The clipboard can still contain data even if the clipboard is not currently 
owned. 
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HWND GetClipboardViewer( ) 


This function retrieves the window handle of the first window in the 
clipboard-viewer chain. 


This function has no parameters. 


Return Value 


The return value identifies the window currently responsible for displaying 
the clipboard. It is NULL if there is no viewer. 


short GetClipBox(hDO, lpRect) 


This function retrieves the dimensions of the tightest bounding rectangle 
around the current clipping boundary. The dimensions are copied to the 
buffer pointed to by the IpRect parameter. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
lpRect LPRECT Points to the RECT data structure that 


is to receive the rectangle dimensions. 


Return Value 


The return value specifies the clipping region’s type. It can be any one of 
the following values: 


COMPLEXREGION Clipping region has overlapping borders. 
ERROR Device context is not valid. 

NULLREGION Clipping region is empty. 

SIMPLEREGION Clipping region has no overlapping borders. 
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HANDLE GetCodeHandle(/pProc) 


This function determines which code segment contains the function 
pointed to by the /pProc parameter. 


Parameter Type/Description 


lpProc FARPROC Is a procedure-instance address. 


Return Value 


The return value identifies the code segment that contains the function. 


Comments 


If the code segment that contains the function is already loaded, the 
GetCodeHandle function marks the segment as recently used. If the 
code segment is not loaded, Get CodeHandle attempts to load it. Thus, 
an application can use this function to attempt to preload one or more 
segments needed to perform a particular task. 


short GetCommError(nCid, lpStat) 


In case of a communications error, Windows locks the communications 
port until the error is cleared by using the GetCommError function. 
This function fills the status buffer pointed to by the /pStat parameter 
with the current status of the communication device specified by the nCid 
parameter. It also returns the error codes that have occurred since the last 
GetCommError call. If [pStat is NULL, only the error code is returned. 
For a list of the error codes, see Table 3.8. 


Parameter Type/Description 

nCid int Specifies the communication device to be exam- 
ined. 

lpStat LPSTR Points to the COMSTAT structure that 


is to receive the device status. The structure contains 
information about a communication device. 
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GetCommError 


The return value specifies the error codes returned by the most recent 
communications function. It can be any of the values given in Table 3.8: 


Table 3.8 
Error Codes 


Value 
CE_ BREAK 
CE_ CTSTO 


CE_ DNS 
CE_ DSRTO 


CE_ FRAME 
CE_ JOE 
CE_ MODE 


CE_ OOP 
CE_ OVERRUN 


CE_ PTO 


CE_RLSDTO 


CE_ RXOVER 


CE_ RXPARITY 
CE_ TXFULL 


Meaning 


The hardware detects a break condition. 


Clear-to-send timeout. CTS is low for the duration 
specified by CtsTimeout while trying to transmit a 
character. 


The parallel device is not selected. 


Data-set-ready timeout. DSR is low for the duration 
specified by Dsr Timeout while trying to transmit a 
character. 


The hardware detects a framing error. 


An I/O error occurs while trying to communicate with a 
parallel device. 


Requested mode is not supported, or the nCid parameter 
is invalid. If set, this is the only valid error. 


The parallel device signals that it is out of paper. 


A character is not read from the hardware before the next 
character arrives. The character is lost. 


Timeout occurs while trying to communicate with a 
parallel device. 


Receive-line-signal-detect timeout. RLSD is low for the 
duration specified by Rlsd Timeout while trying to 
transmit a character. 


Receive queue overflow. There is either no room in the 
input queue or a character is received after the EofChar 
character is received. 


The hardware detects a parity error. 


The transmit queue is full while trying to queue a 
character. 
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WORD GetCommEventMask(nCid, nEvtMask) 


This function retrieves the value of the current event mask, and then 
clears the mask. This function must be used to prevent loss of an event. 


Parameter Type/ Description 

nCid int Specifies the communication device to be exam- 
ined. 

nEviMask int Specifies which events are to be enabled. For a list 


of the event values, see the Set CommEventMask 
function, later in this chapter. 


Return Value 


The return value specifies the current event-mask value. Each bit in the 
event mask specifies whether a given event has occurred. A bit is set to 1 
if the event has occurred. 


short GetCommState(nCid, IpDCB) 


This function fills the buffer pointed to by the IpDCB parameter with the 
device control block of the communication device specified by the nCid 
parameter. 


Parameter Type/ Description 


nCid int Specifies the device to be examined. 


lpDCB LPSTR Points to the DCB data structure that is to 
receive the current device control block. The structure 
defines the control setting for the device. 


Return Value 


The return value specifies the outcome of the function. It is zero if the 
function was successful. If an error occurred, the return value is negative. 
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DWORD GetCurrentPosition(hDC) 


This function retrieves the logical coordinates of the current position. 


Parameter Type/ Description 


ADC HDC Identifies a device context. 


Return Value 


The return value specifies the current position. The ycoordinate is in the 
high-order word; the 2coordinate is in the low-order word. 


HANDLE GetCurrentTask( ) 

This function returns the handle of the currently executing task. 
This function has no parameters. 

Return Value 


The return value identifies the task if the function is successful. Otherwise, 


it is NULL. 


DWORD GetCurrentTime{( ) 


This function retrieves the current Windows time. Windows time is the 
number of milliseconds that have elapsed since the system was booted. 


This function has no parameters. 
Return Value 


The return value specifies the current time (in milliseconds). 


Comments 

The GetCurrent Time and GetMessageTime functions return different 
times. GetMessageTime returns the Windows time when the given mes- 
sage was created, not the current Windows time. 


The system timer eventually overflows and resets to zero. 
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void GetCursorPos(IpPoint) 


This function retrieves the cursor’s current position (in screen coordi- 
nates), that copies them to the POINT structure pointed to by the 
lpPoint parameter. 


Parameter Type/Description 


lpPoint - LPPOINT Points to the POINT structure that is 


to receive the screen coordinates of the cursor. 


Return Value 


None 


Comments 


The cursor position is always given in screen coordinates and is not 
affected by the mapping mode of the window that contains the cursor. 


HDC GetDC(hWnd) 


This function retrieves a handle to a display context for the client area 
of the given window. The display context can be used in subsequent GDI 
functions to draw in the client area. 


The GetDC function retrieves a common, class, or private display context 
depending on the class style specified for the given window. For common 
display contexts, GetDC assigns default attributes to the context each 
time it is retrieved. For class and private contexts, GetDC leaves the pre- 
viously assigned attributes unchanged. 


Parameter Type/Description 


hWnd HWND Identifies the window whose display context 


is to be retrieved. 


Return Value 


The return value identifies the display context for the given window’s 
client area if the function is successful. Otherwise, it 1s NULL. 


268 


GetDeviceCaps 


Comments 


After painting with a common display context, ReleaseDC must be called 
to release the context. Class and private display contexts do not have to 
be released. Since only five common display contexts are available at any 
given time, failure to release a display context can prevent other applica- 
tions from accessing a display context. 


LONG GetDCOrg(hDO) 


This function obtains the final translation origin for the device context. 
The final translation origin specifies the offset used by Windows to trans- 
late device coordinates into client coordinates for points in an applica- 
tion’s window. The final translation origin is relative to the physical origin 
of the screen display. 


Parameter Type/Description 


hDC HDC Identifies the device context whose origin 1s to 
be retrieved. 


Return Value 
The return value specifies the final translation origin (in device coordi- 


nates). The y-coordinate is in the high-order word; the zcoordinate is in 
the low-order word. : 


short GetDeviceCaps(hDC, nIndez) 


This function retrieves device-specific information about a given display 
device. The n/ndex parameter specifies the type of information desired. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
nindex short Specifies the item to return. It can be any one 


of the values given in Table 3.9. 


Return Value 


The return value specifies the value of the desired item. 
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Comments 


Table 3.9 lists the values for the nlndez parameter: 


Table 3.9 
GDI Information Indexes 
Index Meaning 
DRIVERVERSION Version number (100H). 
TECHNOLOGY Device technology. It can be any one of the following 
values: 
Value Meaning 
0 Vector plotter 
1 Raster display 
2 Raster printer 
3 Raster camera 
4 Character stream, PLP 
5 Metafile, VDM 
6 Display file 
HORZSIZE Width of the physical display (in millimeters). 
VERTSIZE Height of the physical display (in millimeters). 
HORZRES Width of the display (in pixels). 
VERTRES Height of the display (in raster lines). 
LOGPIXELSX Number of pixels per logical inch along the display width. 
LOGPIXELSY Number of pixels per logical inch along the display height. 
BITSPIXEL Number of adjacent color bits for each pixel. 
PLANES Number of color planes. 
NUMBRUSHES Number of device-specific brushes. 
NUMPENS Number of device-specific pens. 
NUMFONTS Number of device-specific fonts. 
NUMCOLORS Number of entries in the device’s color table. 
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Table 3.9 (continued) 


Index 


ASPECTX 
ASPECTY 
ASPECTXY 


PDEVICESIZE 
CLIPCAPS 


RASTERCAPS 


CURVECAPS 


Meaning 


Relative width of a device pixel as used for line drawing. 
Relative height of a device pixel as used for line drawing. 


Diagonal width of the device pixel as used for line 
drawing. 


Size of the PDEVICE internal data structure. 


Flag that indicates the clipping capabilities of the device. 
lt is 1 if the device can clip to a rectangle, 0 if it cannot. 


Value that indicates the raster capabilities of the device, 
as shown in the following list: 


Capability Meaning 

RC_ BANDING Requires banding support. 
RC_BITBLT Capable of transferring bitmaps. 
RC_ BITMAP64 Capable of supporting bitmaps 


larger than 64K. 


RC_ GDI20_ OUTPUT Capable of supporting 
Windows 2.0 features. 


RC_ SCALING Capable of scaling. 


A bitmask that indicates the curve capabilities of the 
device. The bits have the following meanings: 


Bit Meaning 


Device can do circles. 
Device can do pie wedges. 


Device can do chord arcs. 


0 

1 

2 

3 Device can do ellipses. 
4 Device can do wide borders. 
5 Device can do styled borders. 
6 


Device can do borders that are wide and 
styled. 


7 Device can do interiors. 


The high byte is 0. 
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Table 3.9 (continued) 


Index 
LINECAPS 


POLYGONALCAPS 
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Meaning 


A bitmask that indicates the line capabilities of the 
device. The bits have the following meanings: 


Bit 


TF oO FP WS DO FH © 


Meaning 


Reserved. 

Device can do polyline. 

Reserved. 

Reserved. 

Device can do wide lines. 

Device can do styled lines. 

Device can do lines that are wide and styled. 


Device can do interiors. 


The high byte is 0. 


A bitmask that indicates the polygonal capabilities of the 
device. The bits have the following meanings: 


Bit Meaning 

0 Device can do alternate fill polygon. 

1 Device can do rectangle. 

2 Device can do winding number fill polygon. 

3 Device can do scanline. 

4 Device can do wide borders. 

5 Device can do styled borders. 

6 Device can do borders that are wide and 
styled. 

7 Device can do interiors. 

The high byte is 0. 


Table 3.9 (continued) 


Index 
TEXTCAPS 


Meaning 


GetDeviceCaps 


A bitmask that indicates the text capabilities of the 
device. The bits have the following meanings: 


Bit 


oOo F nt OS Oo & &O WH —& OS 


a a ee 
ao ke WS bo = © 


Meaning 


Device can do character output precision. 
Device can do stroke output precision. 
Device can do stroke clip precision. 

Device can do 90-degree character rotation. 
Device can do any character rotation. 

Device can do scaling independent of Xand Y. 
Device can do doubled character for scaling. 
Device can do integer multiples for scaling. 
Device can do any multiples for exact scaling. 
Device can do double-weight characters. 
Device can do italicizing. 

Device can do underlining. 

Device can do strikeouts. 

Device can do raster fonts. 

Device can do vector fonts. 


Reserved. Must be returned zero. 


For a list of all the available abilities, see the LOGFONT data structure 
in Chapter 6, “Data Types and Structures.” 
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HWND GetDlgItem(hDlg, nIDDigItem) 


This function retrieves the handle of a control contained in the dialog box 
specified by the hDlg parameter. 


Parameter Type/ Description 

hDlg HWND Identifies the dialog box that contains the 
control. 

nlDDigltem int Specifies the integer ID of the item to be 
retrieved. 


Return Value 


The return value identifies the given control. It is NULL if no control with 
the integer ID given by the nJDDigltem parameter exists. 


Comments 


The GetDlgItem function can be used with any parent-child window 
pair, not just dialog boxes. As long as the ADig parameter specifies a 
parent window and the child window has a unique ID (as specified by the 
hMenu parameter in the Create Window function that created the child 
window), GetDlgItem returns a valid handle to the child window. 


unsigned GetDlgltemInt(hDlg, nIDDigltem, lp Translated, bSigned) 


This function translates the text of a control in the given dialog box into 
an integer value. The GetDlgItemInt function retrieves the text of the 
control identified by the nJDDigliem parameter. It translates the text by 
stripping any extra spaces at the beginning of the text and converting 
decimal digits, stopping the translation when it reaches the end of the text 
or encounters any non-numeric character. If the bSigned parameter is non- 
zero, GetDlgItemInt checks for a minus sign (—) at the beginning of the 
text and translates the text into a signed number. Otherwise, it creates an 
unsigned value. 


GetDlgItemInt returns zero if the translated number is greater than 
32,767 (for signed numbers) or 65,535 (for unsigned). When errors occur, 
such as encountering non-numeric characters and exceeding the given 
maximum, GetDlgItemInt copies zero to the location pointed to by the 
lo Translated parameter. If there are no errors, /p Translated receives a 
nonzero value. If Ip Translated is NULL, GetDlgItemInt does not warn 
about errors. GetDIgItemInt sends a WM_GETTEXT message to the 
control. 
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Parameter Type/Description 
hDlq HWND Identifies the dialog box. 
nlIDDigliem int Specifies the integer identifier of the dialog-box 


item to be translated. 


lo Translated BOOL FAR * Points to the Boolean variable that is 


to receive the translated flag. 


bSigned BOOL Specifies whether the value to be retrieved is 
signed. 


Return Value 


The return value specifies the translated value of the dialog-box item text. 
Since zero is a valid return value, the lp Translated parameter must be used 
to detect errors. If a signed return value is desired, it should be cast as an 
int type. 


int GetDigItemText(hDlg, nIDDigltem, lpString, nMazCount) 


This function retrieves the caption or text associated with a control in a 
dialog box. The GetDlgItemText function copies the text to the location 
pointed to by the /pString parameter and returns a count of the number of 
characters 1t copies. 


GetDlgItem Text sends a WM_ GETTEXT message to the control. 


Parameter Type/Description 
hDlg HWND identifies the dialog box that contains the 
control. 
nlDDigltem int Specifies the integer identifier of the dialog-box 
item whose caption or text is to be retrieved. 
lpString LPSTR Points to the buffer to receive the text. 
nMaxCount int Specifies the maximum length : bytes) of 
the string to be copied to lpString. If the string is 


longer than nMazCount, it is truncated. 


Return Value 


The return value specifies the actual number of characters copied to the 
buffer. It is zero if no text is copied. 
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WORD GetDoubleClickTime( ) 


This function retrieves the current double-click time for the mouse. A 
double-click is a series of two clicks of the mouse button, the second 
occurring within a specified time after the first. The double-click time 

is the maximum number of milliseconds that may occur between the first 
and second click of a double-click. 


This function has no parameters. 


Return Value 


The return value specifies the current double-click time (in milliseconds). 


short GetEnvironment(lpPortName, lpEnviron, nMaxCount) 


This function retrieves the current environment that is associated with the 
device attached to the system port specified by the /pPoritName parameter, 
and copies it into the buffer specified by the /p#nviron parameter. The 
environment, maintained by GDI, contains binary data used by GDI when- 
ever a device context is created for the device on the given port. 


The function fails if there is no environment for the given port. 


Parameter Type/Description 

lpPortName LPSTR Points to the null-terminated character 
string that specifies the name of the desired port. 

loEnviron LPSTR Points to the buffer that will receive the 
environment. 

nMaxCount WORD | Specifies the maximum number of bytes to 


copy to the buffer. 


Return Value 


The return value specifies the number of bytes copied to IpEnviron. It is 
zero if the environment cannot be found. 


Comments 


The first field in the buffer pointed to by IpEnviron must be the same as 
that passed in the lpDeviceName parameter of the CreateDC function. If 
lpPortName specifies a null port (as defined in the win.zni file), the device 
name pointed to by lpEnviron is used to locate the desired environment. 
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HWND GetFocus( ) 


This function retrieves the handle of the window that currently owns the 
input focus. 


This function has no parameters. 


Return Value 


The return value identifies the window that currently owns the focus if the 
function is successful. Otherwise, it 1s NULL. 


BYTE GetGValue(rgbColor) 


This macro extracts the green value from an RGB color value. 


Parameter Type/Description 


rgbColor long Specifies a red, a green, and a blue color fielg 
each specifying the intensity of the given color, 


Return Value 


The return value specifies a byte that contains the green value of the 
rgbColor parameter. 


Comments 


The value OF FH corresponds to the maximum intensity value for a single. 
byte; OOOH corresponds to the minimum intensity value for a single byte. 


BOOL GetInputState( ) 


This function determines whether there are mouse, keyboard, or timer 
events in the system queue that require processing. An event is a record 
that describes interrupt-level input. Mouse events occur when a user 
moves the system mouse or clicks a mouse button. Keyboard events ocey, 
when a user presses one or more keys. Timer events occur after a specified 
number of clock ticks. The system queue is the location in which Windows 
stores mouse, keyboard, and timer events. 


This function has no parameters. 


277 


GetInputState 


Return Value 


The return value specifies whether mouse, keyboard or timer input occurs. 
It is nonzero if input is detected. Otherwise, 1t 1s zero. 


int GetInstanceData(hInstance, pData, nCount) 


This function copies data from a previous instance of an application into 
the data area of the current instance. The A/nstance parameter specifies 
which instance to copy data from, pData specifies where to copy the data, 
and nCount specifies the number of bytes to copy. 


Parameter Type/ Description 


hInstance HANDLE Identifies a previous call of the applica- 
tion. 

pData PSTR Points to a buffer in the current instance. 

nCount int Specifies the number of bytes to copy. 


Return Value 


The return value specifies the number of bytes actually copied. 


void GetKeyboardState(lpKeyState) 


This function copies the status of the 256 virtual-keyboard keys to the 
buffer specified by the lpKeyState parameter. The high bit of each byte is 
set to 1 if the key is down, or it is set to 0 if it is up. The low bit is set to 1 
if the key was pressed an odd number of times since startup; otherwise, it 
is set to 0. 


Parameter Type/Description 


lpnKeyState LPSTR Points to the 256-byte buffer of virtual key- 
codes, 


Return Value 


None ae 
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Comments 
To obtain state information for individual keys, follow these steps: 


Create an array of characters that is 265 bytes long. 


2. Copy the contents of the buffer pointed to by the IpKeyState 
parameter into the array. 


3. Use the virtual keycode from Table 3.10 to obtain an individual 
key state. 


int GetKeyState(nVirikey) 


This function retrieves the state of the virtual key specified by the 
nVirtKey parameter. The state specifies whether the key is up, down, 
or toggled. 


Parameter Type/Description 


nVirtKey int Specifies a virtual key. If the desired virtual key is 
a letter or digit (A through Z, a through z, or 0 through 
®) nVirtKey must be set to the ASCII value of that 
character. For other keys, it must be one of the follow- 
ing values listed in Table 3.10. 


Return Value 

The return value specifies the state of the given virtual key. If the high- 
order bit is 1, the key is down. Otherwise, it is up. If the low-order bit is 1, 
the key is toggled. A toggle key, such as the CAPSLOCK key, is toggled if it 


has been pressed an odd number of times since the system was started. 
The key is untoggled if the low bit is 0. 


Comments 


Table 3.10 lists the virtual-key values for the nVirtKey parameter: 
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Table 3.10 
Virtual Keys 


Key 


VK_ LBUTTON 
VK_ RBUTTON 
VK_ MBUTTON 
VK_ BACK 

VK_ TAB 

VK_ RETURN 
VK_ SHIFT 
VK_ CONTROL 
VIK~ MENU 
VK_ CAPITAL 
VK_ INSERT 
VK_~ DELETE 
VK_ CLEAR 
VIL. ESCAPE 
VK_ HELP 

VK NUMLOCK 
VK_ NUMPADO 
Vi_ NUMPAD1 
VIK_ NUMPAD2 
VK_~ NUMPAD3 
VK_ NUMPAD4 
VK_~ NUMPAD5 
VK~ NUMPAD6 
VK~ NUMPAD7 
VK_~ NUMPAD8 
VK NUMPAD9 
VK~ MULTIPLY 
VK_ ADD 


VK_ SEPARATOR 


VK_ SUBTRACT 


Meaning 


Left mouse button 
Right mouse button 
Middle mouse button 
BACKSPACE key 

TAB key 

ENTER key 

SHIFT key 

CONTROL (CTRL) key 
ALTERNATE (ALT) key 
CAPSLOCK key 
INSERT key 

DELETE key 

CLEAR key 

ESCAPE (ESC) key 
HELP key 

NUMLOCK key 
Numeric keypad 0 
Numeric keypad 1 
Numeric keypad 2 
Numeric keypad 3 
Numeric keypad 4 
Numeric keypad 5 
Numeric keypad 6 
Numeric keypad 7 
Numeric keypad 8 
Numeric keypad 9 
Multiply key 

Add key 

Separator key 
Subtract key 


GetKeyState 


Table 3.10 (continued) 


Key Meaning 

VK_~ DECIMAL Decimal-point key 
VI_ DIVIDE Divide key 

VK_ SPACE SPACEBAR 

VK_ PRIOR Prior Screen key 
VK_ NEXT Next Screen key 
VK_ END End of document key 
VK_ HOME HOME key 

VIK_ CANCEL CANCEL key 
VIX. PAUSE PAUSE key 

VK_ LEFT Left arrow key 
Vik_ UP Up arrow key 
VK_ RIGHT Right arrow key 
VIK_ DOWN Down arrow key 
VIC_ SELECT SELECT key 
VK_ PRINT PRINT key 
VK_FI1 F1 key 

VK_F2 F2 key 

VK_F3 F3 key 

VK_ F4 F4 key 

VK_F5 F5 key 

VK_F6 F6 key 

VK_F7 F7 key 

VK_F8 F8 key 

VK_F9 F9 key 

VIK_ F10 F10 key 
VK_F11 F11 key 
VIK_F12 F12 key 
VK_F13 F13 key 
VIK_F14 F14 key 
VIK_FI15 F15 key 

VIK_ F16 F16 key 
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short GetMapMode(hDC) 


This function retrieves the current mapping mode. See the SeCMapMode 
function, later in this chapter, for a description of the mapping modes. 


Parameter Type/Description 
hDC HDC Identifies the device context. 


Return Value 


The return value specifies the mapping mode. 


HMENU GetMenu(hWnd) 


This function retrieves a handle to the menu of the specified window. 


Parameter Type/Description 


hWnd HWND Identifies the window whose menu Is to be 
examined. 


Return Value 


The return value identifies the menu. It is NULL if the given window has 
no menu. 


WORD GetMenultemCount(hMenu) 


This function determines the number of items in the menu identified by 
the hMenu parameter. This may be either a pop-up or a top-level menu. 


Parameter Type/Description 
hMenu HMENU | Identifies the handle to the menu to be 
examined. 


Return Value 


The return value specifies the number of items in the menu specified by the 
hMenu parameter if the function is successful. Otherwise, it 1s —1. 
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WORD GetMenultemID(iMenu, nPos) 


This function obtains the menu-item identifier for a menu item located at 
the position defined by the nPos parameter. 


Parameter Type/Description 


hMenu HMENU Identifies a handle to the pop-up menu that 
contains the item whose ID is being retrieved. 


nPos int Specifies the position (zero-based) of the menu 
item whose ID is being retrieved. 


Return Value 


The return value specifies the item ID for the specified item in a pop-up 
menu if the function is successful; if hMenu is NULL or if the specified item 
is a pop-up menu (as opposed to an item within the pop-up menu), the 
return value is —1. 


WORD GetMenuState(hMenu, wld, wFlags) 


This function obtains the number of items in the pop-up menu associated 
with the menu item specified by the wld parameter if the hMenu parameter 
identifies a top-level menu. If hMenu identifies a pop-up menu, this func- 
tion obtains the status of the menu item associated with wld. 


Parameter Type/Description 

hMenu HMENU _ Identifies the menu. 

wld WORD Specifies the menu-item ID. 

wk lags WORD Specifies the nature of the wid parameter. If 


the wklags parameter contains MF_ BYPOSITION, wld 
specifies a (zero-based) relative position; if wKlags con- 
tains MF_ BYCO ND, wld specifies the item ID. 


Return Value 


The return value specifies the outcome of the function. It is NULL if the 
menu or specified item does not exist. If wid identifies a pop-up menu, 
the return value is the number of items in the pop-up menu; otherwise, it 
is a mask (Boolean OR) of the values from the following list (this mask 
describes the status of the menu item that wld identifies): 
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MF_ CHECKED a is placed next to item (pop-up menus 
only). 


MF_ DISABLED Item is disabled. 
MF_ ENABLED Item is enabled. 


MF_ MENUBARBREAK 
Same as MF_. MENUBREAK, except for pop-up 
menus, where the new column is separated from the 
old column by a vertical dividing line. 


MF_.MENUBREAK _ Item is placed on a new line (static menus) or in a 
new column (pop-up menus) without separating 
columns. 


MF_SEPARATOR Horizontal dividing line is dravn( pop-up menus 
only). This line cannot be enabled, checked, grayed, 
or highlighted. The lpNewltem and wiDNewltem 


parameters are ignored. 


MF..UNCHECKED  Checkmark is not placed next to item (default). 


int GetMenuString(hMenu, wlDItem, lpString, nMaxCount, wFlag) 


This function copies the label of the specified menu item into the IpString 
parameter. 


Parameter Type/Description 
hMenu HMENU Identifies the menu. 
wlDlitem WORD Specifies the integer identifier of the menu 


item (from the resource file) or the offset of the menu 
item in the menu, depending on the value of the wklag 


parameter. 

lpString LPSTR Points to the buffer that is to receive the 
label. : 

nMaxCount int Specifies the maximum length of the label to 


be copied. If the label is longer than the maximum 
specified in nMazCount, the extra characters are 
truncated. 


wklag WORD Specifies the nature of the wlD parameter. 
If wFlags contains MF_BYPOSITION, wild specifies a _ 
(zero-based) relative position; if the wklags parameter 


contains MF. BYCOMMAND, wild specifies the item ID. 
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Return Value 


The return value specifies the actual number of bytes copied to the buffer. 


Comments 


The nMazCount parameter should be one larger than the number of char- 
acters in the label to accommodate the null character that terminates a 
string. 


BOOL GetMessage(lpMsg, hWnd, wMsgFilterMin, wMsgFilterMaz) 


This function retrieves a message from the application queue and places 
the message in the data structure pointed to by the lpMsg parameter. If 
no message is available, the GetMessage function yields control to other 
applicatons until a message becomes available. 


GetMessage retrieves only messages associated with the window specified 
by the hWnd parameter and within the range of message values given by 
the wMsgFilterMin and wMsgFilterMaz parameters. If hWnd is NULL, 
GetMessage retrieves messages for any window that belongs to the appli- 
cation making the call. (The GetMessage function does not retrieve mes- 
sages for windows that belong to other applications.) If wMsgFilterMin and 
wMsgFilterMaz are both zero, GetMessage returns all available messages 
(no filtering is performed). 


The constants WM_ KEYFIRST and WM_KEYLAST can be used as filter 
values to retrieve all messages related to keyboard input; the constants 
WM MOUSEFIRST and WM_ MOUSELAST can be used to retrieve all 


mouse-related messages. 


Parameter Type/Description 

lpMsq LPMSG Points to an MSG data structure that con- 
tains message information from the Windows applica- 
tion queue. 

hWnd HWND Identifies the window whose messages are to 


be examined. If hWnd is NULL, GetMessage retrieves 
messages for any window that belongs to the applica- 
tion making the call. 


wMsghilterMin unsigned Specifies the integer value of the lowest 
message to be examined. 


wMsgFilterMax unsigned Specifies the integer value of the highest 
message to be examined. 
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Return Value 


The return value specifies the outcome of the function. It is nonzero if a 
message other than WM. QUIT is retrieved. It is zero if the WM_ QUIT 


message Is retrieved. 


The return value is usually used to decide whether to terminate the 
application’s main loop and exit the program. 


Comments 


In addition to yielding control to other applications when no messages are 
available, the GetMessage and PeekMessage functions also yield con- 
trol when WM_PAINT or WM_ TIMER messages are available. 


The GetMessage, PeekMessage, and WaitMessage functions are the 
only ways to let other applications run. If your application does not call 
any of these functions for long periods of time, other applications can- 
not run. 


When GetMessage, PeekMessage, and WaitMessage yield control to 
other applications, the stack and data segments of the application calling 
the function may move in memory to accommodate the changing memory 
requirements of other applications. If the application has stored long 
pointers to objects in the data or stack segment (that is, global or local 
variables), these pointers can become invalid after a call to GetMessage, 
PeekMessage, or WaitMessage. The l[pMsg parameter of the called func- 
tion remains valid in any case. 


DWORD GetMessagePos( ) 


This function returns a long value that represents the mouse position (in 
screen coordinates) when the last message obtained by the GetMessage 
function occurred. 


This function has no parameters. 


Return Value 


The return value specifies the # and ycoordinates of the mouse posi- 
tion. The zcoordinate is in the low-order word, and the y coordinate is in 
the high-order word. If the return value is assigned to a variable, the 
MAKEPOINT macro can be used to obtain a POINT structure from 
the return value; the LOWORD or HIWORD macro can be used to 
extract the a or the ycoordinate. 
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Comments 


To obtain the current position of the mouse cursor instead of the position 
when the last message occurred, use the GetCursorPos function. 


long GetMessageTime( ) 

This function returns the message time for the last message retrieved 
by the GetMessage function. The time is a long integer that specifies 
the elapsed time (in milliseconds) from the time the system was booted 
to the time the message was created {placed in the application queue). 


This function has no parameters. 


Return Value 


The return value specifies the message time. 


Comments 

Do not assume that the return value is always increasing. The return value 
will “wrap around” to zero if the timer count exceeds the maximum value 
for long integers. 


To calculate time delays between messages, subtract the time of the 
second message from the time of the first message. 


HANDLE GetMetaFile(/pFilename) 


This function creates a handle for the metafile named by the IpFilename 
parameter. 


Parameter Type/Description 
_lpFilename LPSTR Points to the null-terminated character 


string that specifies the DOS filename of the metafile. 
The metafile is assumed to exist. 


Return Value 


The return value identifies a metafile if the function is successful. Other- 


wise, it is NULL. 


287 


GetMetaFileBits 


HANDLE GetMetaFileBits(hMF) 


This function returns a handle to a global memory block that contains the 
specified metafile as a collection of bits. The memory block can be used to 
determine the size of the metafile or to save the metafile as a file. The 
memory block should not be modified. 


Parameter Type/Description 
AMF HANDLE Identifies the memory metafile. 


Return Value 


The return value identifies the global memory block that contains the 
matafile. If an error occurs, the return value is NULL. 


Comments 


The handle used as the hMF parameter becomes invalid when the Get- 
MetaFileBits function returns, so the returned global memory handle 
must be used to refer to the metafile. 


Memory blocks created by this function are unique to the calling applica- 
tion and are not shared by other applications. These blocks are automati- 
cally deleted when the application terminates. 


int GetModuleFileName(hModule, lpFilename, nSize) 


This function retrieves the name of the executable file from which the 
specified module was loaded. The function copies the null-terminated 
filename into the buffer pointed to by the lpFilename parameter. 


Parameter Type/Description 

hModule HANDLE Identifies the module or the instance of 
the module. 

loFilename LPSTR Points to the buffer that is to receive the 
filename. 

nSize int Specifies the maximum number of characters to 


copy. If the filename is longer than the maximum 
number of characters specified by the nSize parameter, 
it is truncated. 
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Return Value 


The return value specifies the actual length of the string copied to the 
buffer. — 


HANDLE GetModuleHandle(lpModuleName) 
This function retrieves the module handle of the specified module. 
Parameter Type/Description 


lnModuleName LPSTR Points to a null-terminated character string 
that specifies the module. 


Return Value 


The return value identifies the module if the function is successful. Other- 


wise, 1t is NULL. 


int GetModuleUsage(hModule) 


This function returns the reference count of a specified module. 


Parameter Type/ Description 
hModule HANDLE Identifies the module or an instance of the 
module. 


Return Value 


The return value specifies the reference count of the module. 


DWORD GetNearestColor(hDC, rgbColor) 


This function returns the closest logical color to a specified logical color 
the given device can represent. 


Parameter Type/Description 
ADC HDC Identifies the device context. 
rgbColor DWORD _ Specifies an RGB color value that specifies 


the color to be matched. 
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Return Value 


The return value specifies an RGB color value that names the solid color 
closest to the rgbColor value that the device can represent. 
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HWND GetNextDlgGroupltem(hDlg, hCil, fPrevious) 


This function searches for the next (or previous) control within a group 
of controls in the dialog box identified by the hDlg parameter. A group of 
controls consists of one or more controls with WS_ GROUP style. 


Parameter Type/Description 

hDig HWND sidentifies the dialog box being searched. 

hcl HWND Identifies the control in the dialog box where 
the search starts. 

{Previous BOOL Specifies how the function is to search the 


group of controls in the dialog box. If the fPrevious 
parameter is zero, the function searches for the previous 
control in the group. If fPrevious is nonzero, the func- 
tion searches for the next control in the group. 


Return Value 


The return value identifies the next or previous control in the group. 


Comments 


If the current item is the last item in the group and {Previous is zero, Get- 
NextDlgGrouplItem returns the window handle of the first item in the 
group. If the current item is the first item in the group and {Previous is 
nonzero, GetNextDl]gGroupItem returns the window handle of the last 
item in the group. 


HWND GetNextDlgTablItem(hDig, hCil, fPrevious) 


This function obtains the handle of the first control that has the 
WS_ TABSTOP style that precedes (or follows) the control identified 
by the AC#l parameter. 
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Parameter Type/Description 

hDlg HWND _Identifies the dialog box being searched. 

hcl HWND _ Identifies the control to be used as a starting 
point for the search. 

[Previous BOOL Specifies how the function is to search the 


dialog box. If the fPrevious parameter is zero, the func- 
tion searches for the previous control in the dialog box. 
If {Previous is nonzero, the function searches for the 
next control in the dialog box. Identifies the control to 
be used as a starting point for the search. 


Return Value 


The return value identifies the previous (or next) control that has the 
WS TABSTOP style set. 


HWND GetNextWindow(hWnd, wFlag) 


This function searches for a handle that identifies the next (or previous) 
window in the window-manager’s list. The window-manager’s list contains 
entries for all top-level windows, their associated child windows, and the 
child windows of any child windows. If the hWnd parameter is a handle to 
a, top-level window, the function searches for the next (or previous) handle 
to a top-level window; if hWnd is a handle to a child window, the function 
searches for a handle to the next (or previous) child window. 


Parameter Type/Description 
hWnd HWND _Identifies the current window. 
wklag WORD _ Specifies whether the function returns a han- 


dle to the next window or to the previous window. It 
can be either of the following values: 


Value Meaning 


GW. HWNDNEXT ~~ The function returns a handle to 


the next window. 


GW_HWNDPREV _ The function returns a handle to 


the previous window. 
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Return Value 


The return value identifies the next (or the previous) window in the 
window-manager’s list. 


Comments 


The windows in the window-manager’s list are ordered according to their 
visibility on the display. The top-level window that takes up the greatest 
amount of space is the first entry in the list. 


WORD GetNumTasks( ) 


This function returns the number of tasks currently executing in the sys- 
tem. A task is a unique instance of a Windows application; it consists of a 
code segment (which will be common to other instances of the same appli- 
cation) and a data segment (which is not common to other instances of the 
same application). 


This function has no parameters. 


Return Value 


The return value specifies an integer that represents the number of tasks 
currently executing in the system. | 


short GetObject(hObject, nCount, pObject) 


This function fills a buffer with the logical data that defines the logical 
object specified by the hObject parameter. The GetObject function copies 
the number of bytes of data specified by the nCount parameter to the 
buffer pointed to by the [pObject parameter. The function returns data 
structures of the LOGPEN, LOGBRUSH, LOGFONT, or BITMAP 
type, depending on the logical object. The buffer must be sufficiently large 
to receive the data. 


Parameter Type/Description 


hObject HANDLE Identifies a logical pen, brush, font, or bit- 
map. 

nCount short Specifies the number of bytes to be copied to 
the buffer. 
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~ IpObject | LPSTR Points to the buffer that is to receive 
the information. It must be a data structure of 
LOGPEN, LOGBRUSH, LOGFONT, or 
BITMAP type, depending on the logical object 
given. 

Return Value 


The return value specifies the actual number of bytes retrieved. It is zero if 
an error occurs. | | 


Comments 
If hObject specifies.a bitmap, the function returns only the width, height, 


and color format information of the bitmap. The actual bits must be 
retrieved by using the GetBitmapBits function. 


HWND GetParent(hWnd) 


This function retrieves the window handle of the specified window’s parent 
window (if any). 


Parameter Type/Description 


hWnd HWND Identifies the window whose parent window 
handle is to be retrieved. 


Return Value 


The return value identifies the parent window. It is NULL if the window 
has no parent window. | 


DWORD GetPixel(hDC, X, Y) 
This function retrieves the RGB color value of the pixel at the point 


specified by the X and Y parameters. The point must be in the clipping 
region. If the point is not in the clipping region, the function is ignored. 
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Parameter Type/ Description 
hDC HDC _ Identifies the device context. 
xX short Specifies the logical coordinate of the point 


to be examined. 


Y short Specifies the logical ycoordinate of the point 
to be examined. 


Return Value 

The return value specifies an RGB color value for the color of the given 
point. It is -1 if the coordinates do not specify a point in the clipping 
region. 

Comments 

Not all devices support the GetPixel function. For more information, see 


the RC_ BITBLT raster capability in the GetDeviceCaps function, ear- 
lier in this chapter. 


short GetPolyFillMode(hDC) 


This function retrieves the current polygon-filling mode. 


Parameter Type/Description 


hDC HDC _ Identifies the device context. 


Return Value 


The return value specifies the polygon-filling mode. It can be any one of 
the following values: 


ALTERNATE Alternate mode 
WINDING Winding-number mode 


For a description of these modes, see the SetPolyFillMode function, later 
in this chapter. 
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FARPROC GetProcAddress(hModule, lpProcName) 


This function retrieves the memory address of the function whose name is 
pointed to by the /pProcName parameter. The GetProcAddress function 
searches for the function in the module specified by the hModule parame- 
ter, or in the current module if hModule is NULL. The function must be an 
exported function; the module’s definition file must contain an appropriate 


EXPORTS line for the function. 


Parameter Type/Description 


hModule HANDLE Identifies the library module that contains 
the function. 


lpProcName LPSTR Points to the function name, or contains the 
ordinal value of the function. If it is an ordinal value, 
the value must be in the low-order word and zero must 
be in the high-order word. The string must be a null- 
terminated character string. 


Return Value 


The return value points to the function’s entry point if the function is suc- 


cessful. Otherwise, it is NULL. 


Comments 


GetProcAddress should be used to retrieve addresses of exported func- 
tions that belongs to library modules only. The MakeProcInstance 
function can be used to access functions within different instances of the 
current module. 


The spelling of the function name (pointed to by [pProcName) must be 
identical to the spelling as it appears in the source library. 


int GetProfileInt(IpAppName, lpKeyName, nDefault) 
This function retrieves the value of an integer key from the Windows 


initialization file, win.ina. The function searches win.ini for a key that 
matches the name specified by the lpKeyName parameter under the 
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application heading specified by the IpAppName parameter. An integer 
entry in win.zni must have the following form: 


iene name| 
eyname = value 


Parameter Type/Description 


lpAppName LPSTR Points to the name of a Windows applica- 
tion that appears in the Windows initialization file. 

lnKeyName LPSTR Points to a keyname that appears in the 
Windows initialization file. 

nDefault int Specifies the default value for the given key if the 


key cannot be found in the Windows initialization file. 


Return Value 


The return value specifies the result of the function. The return value is 
zero if the value that corresponds to the specified keyname is not an 
integer. If the value that corresponds to the keyname consists of digits fol- 
lowed by nonnumeric characters, the function returns the value of the 
digits. For example, if the entry KeyName=102abc is accessed, the func- 
tion returns 102. If the key is not found, this function returns the default 
value, nDefault. 


int GetProfileString(/pAppName, IpKeyName, |pDefault, 
lpReturnedString, nSize) 


This function copies a character string from the Windows initialization 
file, win.inz, into the buffer pointed to by the lpReturnedString parameter. 
The function searches win.ini for a key that matches the name specified by 
the lpKeyName parameter under the application heading specified by the 
lpAppName parameter. If the key is found, the correponding string is 
copied to the buffer. If the key does not exist, the default character string 
specified by the /pDefault parameter is copied. A string entry in win.int 
must have the following form: 


uae name| 
eyname = value 
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If loKeyName is NULL, the GetProfileString function enumerates all 
keynames associated with lpAppName by filling the location pointed to by 
lpReturnedString with a list of keynames (not values). Each keyname in the 
list is terminated with a null character. The last string in the list is termi- 
nated with two null characters. GetProfileString returns the length of 
the list up to, but not including, the final null character. 


Parameter Type/Description 


lpbAppName LPSTR Points to a null-terminated character string 
that names the application. 


lpKeyName LPSTR Points to a null-terminated character string 
that names a key. 
lpDefault LPSTR Points to a null-terminated character string 


that names a key. 


IpReturnedString LPSTR Points to the buffer that receives the charac- 
ter string. 


nSize int Specifies the number of characters (including the 
last null character) that will be copied to the buffer. 


Return Value 


The return value specifies the number of characters copied to the buffer. 


Comments 


GetProfileString is not case-dependent, so the strings in /pAppName and 
lnKeyName may be in any combination of uppercase and lowercase letters. 


HANDLE GetProp(hWnd, lpString) 


This function retrieves a data handle from the property list of the speci- 
fied window. The character string pointed to by the /[pString parameter 
identifies the handle to be retrieved. The string and handle are assumed to 
have been added to the property list by using the SetProp function. 
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Parameter Type/Description 


hWnd HWND Identifies the window whose property list is 
to be searched. 


lnString LPSTR Points to a null-terminated character string 
or an atom that identifies a string. If an atom 1s given, 
it must have been created previously by using the 
AddAtom function. The atom, a 16-bit value, must be 
placed in the low-order word of the lpString parameter; 
the high-order word must be set to zero. 


Return Value 


The return value identifies the associated data handle if the property list 
contains the given string. Otherwise, it is NULL. 


Comment 


The GetProp function does not ensure that the returned handle is valid 
or in a form that can be used by the application. The application must 
determine whether the handle is valid. It must also determine the method 
required to access the data associated with the handle. 


short GetRelAbs(hDC) 
This function retrieves the relative-absolute flag. This flag specifies 


whether the coordinates in GDI functions are relative to the origin of the 
given device (absolute) or relative to the current position (relative). 


Parameter Type/Description 


hDC HDC Identifies the device context. 


Return Value 


The return value specifies the current mode. It can be ABSOLUTE or 
RELATIVE. It is NULL if the ADC parameter is not a valid device 


context. 
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short GetROP2(hDC) 
This function retrieves the current drawing mode. The drawing mode 


specifies how the pen or interior color and the color already on the dis- 
play surface are combined to yield a new color. 


Parameter Type/Description 


hDC HDC Identifies the device context for a raster device. 


Return Value 


The return value specifies the drawing mode. For a list of the drawing 
modes, see the SetROP2 function, later in this chapter. 


Comments 


For more information about the drawing modes, see Appendix A, “Binary 
and Ternary Raster-Operation Codes and Descriptions.” 


BYTE GetRValue(rgbColor) 


This function extracts the red value from an RGB color value. 


Parameter Type/Description 


rgbColor long Specifies a red, a green, and a blue color field, 
each specifying the intensity of the given color. 


Return Value 


The return value specifies a byte that contains the red value of the 
rgobColor parameter. 


Comments 


The value OFFH corresponds to the maximum intensity value for a single 
byte; OOOH corresponds to the minimum intensity value for a single byte. 
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int GetScrollPos(hWnd, nBar) 


This function retrieves the current position of a scroll-bar thumb. ‘The 
current position is a relative value that depends on the current scrolling 
range. For example, if the scrolling range is 0 to 100 and the thumb is in 
the middle of the bar, the current position 1s 50. 


Parameter Type/Description . 


hWnd HWND Identifies a window that has standard scroll 
bars or a scroll-bar control, depending on the value of 
the nBar parameter. 


nBar int Specifies the scroll bar to examine. It can be one 
of the following values: 


Value Meaning 


SB. CTL Retrieves the position of a 
scroll-bar control. In this 
case, the hWnd parameter 
must be the window handle 
of a scroll-bar control. 


SB_ HORZ Retrieves the position of a 
window’s horizontal scroll bar. 
SB_ VERT Retrieves the position of a 


window’s vertical scroll bar. 


Return Value 


The return value specifies the current position of the scroll-bar thumb. 


void GetScrollRange(hWnd, nBar, lpMinPos, lpMaxPos) 


This function copies the current minimum and maximum scroll-bar posi- 
tions for the given scroll bar to the locations specified by the [pMinPos and 
lpMazPos parameters. If the given window does not have standard scroll 
bars or is not a scroll-bar control, then the GetScrollRange function 
coples zero to [lpMinPos and lpMaxPos. 
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Parameter Type/Description 


hWnd HWND _siIdentifies a window that has standard scroll 
bars or a scroll-bar control, depending on the value of 
the nBar parameter. 


nBar . int Specifies a short-integer value that identifies 
which scroll bar to retrieve. It can be one of the follow- 
ing values: 


Value Meaning 


SB. CTL Retrieves the position of a scroll- 
bar control; in this case, the 
hWnd parameter must be the 
handle of a scroll-bar control. 


SB_ HORZ Retrieves the position of a 


window’s horizontal scroll bar. 
SB. VERT Retrieves the position of a 
| window’s vertical scroll bar. 
loMinPos LPINT Points to the integer variable that is to 
receive the minimum position. 
lpMazxPos LPINT Points to the integer variable that is to 


receive the maximum position. 
Return Value 
None 


Comment 


The default range for a standard scroll bar is 0 to 100. The default range 
for a scroll-bar control is empty (both values are zero). 


HANDLE GetStockObject(nIndez) . 


This function retrieves a handle to one of the predefined stock pens, 
brushes, or fonts. 


Parameter Type/Description 


nindex short Specifies the type of stock object desired. It can 
be any one of the following values: 
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Value 


BLACK ~ BRUSH 
DKGRAY_ BRUSH 
GRAY BRUSH 
HOLLOW_ BRUSH 
LTGRAY_ BRUSH 
NULL_- BRUSH 
WHITE_ BRUSH 
BLACK” PEN 
NULL_ PEN 
WHITE_ PEN 
ANSIL FIXED_ FONT 
ANSIL VAR_ FONT 


DEVICE_ DEFAULT_ FONT 


OEM_ FIXED_ FONT 


SYSTEM. FONT 


Return Value 


Meaning 


Black brush 
Dark gray brush 
Gray brush 
Hollow brush 
Light gray brush 
Null brush 
White brush 
Black pen 

Null pen 

White pen 

ANSI fixed system font 


ANSI variable system 
font 


Device-dependent font 
OEM-dependent fixed 


font 


System-dependent fixed 
font 


The return value identifies the desired logical object if the Functions is suc- 


cessful. Otherwise, it is NULL. 


Comments 


The DKGRAY_ BRUSH, GRAY_ BRUSH, and LTGRAY_ BRUSH objects 
should not be used as background brushes or for any other purpose in a 
window whose class does not specify CS. HREDRAW and CS_ VREDRAW 
styles. Using a gray stock brush in such windows can lead to misalignment 
of brush patterns after a window is moved or sized. Stock-brush origins 


cannot be adjusted a more information, see the SetBrushOrg function, 


later in this chapter 
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short GetStretchBltMode(hDC) 
This function retrieves the current stretching mode. The stretching mode 


defines how information is to be added or removed from bitmaps that are 
stretched or compressed by using the StretchBlt function. 


Parameter Type/Description 
hDC HDC _ Identifies the device context. 


Return Value 


The return value specifies the current stretching mode. It can be 
WHITEONBLACK, BLACKONWHITE, or COLORONCOLOR. For more 
information, see the SetStretchBltMode function, later in this chapter. 


HMENU GetSubMenu(hMenu, nPos) 


This function retrieves the menu handle of a pop-up menu. 


Parameter Type/Description 
hMenu HMENU | Identifies the menu. 
nPos int Specifies the position in the given menu of the 


pop-up menu. Position values start at zero for the first 
menu item. The pop-up menu’s integer ID cannot be 
used in this function. 


Return Value 


The return value identifies the given pop-up menu. It is NULL if no pop-up 
menu exists at the given position. 


DWORD GetSysColor(nJndez) 
This function retrieves the current color of the display element specified by 


the nIndex parameter. Display elements are the various parts of a window 
and the Windows display that appear on the system display screen. 


Parameter Type/Description 
nindex int Specifies the display element whose color is 


to be retrieved. For a list of the index values, see the 
SetSysColor function, later in this chapter. 
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Return Value 


The return value specifies an RGB color value that names the color of the 
given element. 


- Comments 


System colors for monochrome displays are usually interpreted as various 
shades of gray. 


HWND GetSysModalWindow( ) 


This function returns the handle of a system-modal window, if one is 
present. 


This function has no parameters. 


Return Value 


The return value identifies the system-modal window, if one is present. If 
no such window is present, the return value is NULL. 


HMENU GetSystemMenu(hWnd, bRevert) 


This function allows the application to access the system menu for copying 
and modification. 


Parameter Type/Description 

hWnd HWND Identifies the window that will own a copy of 
the system menu. 

bRevert BOOL Specifies the action to be taken. If the bRevert 


parameter is zero, the GetSystemMenu function 

returns a handle to a copy of the system menu. This 

copy is initially identical to the system menu, but can be 

modified. If bRevert is nonzero, GetSystemMenu de- 

stroys the possibly modified copy of the system menu 

(if there is one) that belongs to the specified window and 

returns a handle to the original, unmodified version of ha33 
the system menu. 
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Return Value 


The return value identifies the system menu if bRevert is nonzero and the 
system menu has been modified. If bRevert is nonzero and the system menu 
has not been modified, the return value is NULL. If bRevert is zero, the 
return value identifies a copy of the system menu. 


Comments 


Any window that does not use the GetSystemMenu function to make its 
own copy of the system menu receives the standard system menu. 


The handle returned by the GetSystemMenu function can be used with 
the ChangeMenu function to change the system menu. The system 
menu initially contains items identified with various ID values such as 
SC_ CLOSE, SC. MOVE, and SC_ SIZE. Menu items on the system menu 
send WM_SYSCOMMAND messages. All predefined system-menu items 
have ID numbers greater than F000 (hexadecimal). If an application adds 
commands to the system menu, it should use ID numbers less than F000. 


Windows automatically grays items on the standard system menu, depend- 
ing on the situation. The application can carry out its own checking or 
graying by responding to the WM_INITMENU message, which is sent 
before any menu is displayed. 


int GetSystemMetrics(nJndez) 


This function retrieves the system metrics. The system metrics are the 
widths and heights of various display elements of the Windows display. 
The GetSystemMetrics function can also return flags that indicate 
whether the current version is a debugging version, whether a mouse is 
present, or whether the meaning of the left and right mouse buttons have 
been exchanged. 


Parameter Type/ Description 
nindex int Specifies the system measurement to be retrieved. 
All measurements are given in pixels. The system mea- 


surement must be one of the values listed in Table 3.11. 


Return Value 


The return value specifies the requested system metric. 
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Comments 


System metrics depend on the system display and may vary from display 
to display. Table 3.11 lists the system-metric values for the nJndezx param- 


eter: 
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Table 3.11 

System Metric Indexes 

Index Meaning 

SM. CXSCREEN Width of screen. 

SM_ CYSCREEN Height of screen. 

SMW CXFRAME Width of window frame that 
can be sized. 

SM_ CYFRAME Height of window frame that 
can be sized. 

SM_ CXVSCROLL Width of arrow bitmap on 
vertical scroll bar. 

SM_ CYVSCROLL Height of arrow bitmap on 
vertical scroll bar. 

SM_ CXHSCROLL Width of arrow bitmap on 
horizontal scroll bar. 

SM_ CYHSCROLL Height of arrow bitmap on 
horizontal scroll bar. 

SM_ CYCAPTION Height of caption. 

SM_ CXBORDER Width of window frame that 
cannot be sized. 

SM_ CYBORDER Height of window frame that 
cannot be sized. 

~SM_ CXDLGFRAME Width of frame when window 

has WS_ DLGFRAME style. 

SM_ CYDLGFRAME Height of frame when window 
has WS_ DLGFRAME style. 

SM_ CXHTHUMB Width of thumb box on 
horizontal scroll bar. 

SM_ CYVTHUMB Height of thumb box on 
vertical scroll bar. 

SM_. CXICON Width of icon. 

SM... CYICON Height of icon. 

SM_ CXCURSOR Width of cursor. 

SM_ CYCURSOR Height of cursor. 

SM_ CYMENU Height of single-line menu bar. 


Table 3.11 (continued) 


Index Meaning 

SM_ CXFULLSCREEN Width of window client area for 
full-screen window. 

SMW. CYFULLSCREEN Height of window client area for 
full-screen window (equivalent to 
the height of the screen minus the 
height of the window caption). 

SM_ CYKANJIWINDOW — Height of ICanji window. 

SM_ CXMINTRACK Minimum tracking width of window. 

SM. CYMINTRACK Minimum tracking height of window. 

SM_ CXMIN Minimum width of window. 

SML. CYMIN Minimum height of window. 

SM_ CXSIZE Width of bitmaps contained in the 
title bar. 

SM_ CYSIZE Height of bitmaps contained in the 
title bar. 

SMW. MOUSEPRESENT Nonzero if mouse hardware installed. 

SM_ DEBUG Nonzero if Windows debugging 

| version. 
SM. SWAPBUTTON Nonzero if left and right mouse 


Get TempDrive 


buttons swapped. 


BYTE GetTempDrive(cDrivel etter) 

This function takes a drive letter or zero and returns a letter that specifies 
the optimal drive for a temporary file (the disk drive that can provide the 

best access time during disk operations with a temporary file). 

The GetTempDrive function returns the drive letter of a hard disk if the 
system has one. If the cDriveletter parameter is zero, the function returns 


the drive letter of the current disk; if cDriveLetter is a letter, the function 
returns the letter of that drive or the letter of another available drive. 

Parameter Type/ Description 
cDriveLetter BYTE Specifies a disk-drive letter. 


Return Value 


The return value specifies the optimal disk drive for temporary files. 
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int GetTempFileName(cDriveL etter, lpPrefiaString, wUnique, 
lp TempFileName) 


This function creates a temporary filename of the following form: 
drives\ path\ prefizuuuu.tmp 


In this syntax line, drive is the drive letter specified by the cDriveL etter 
parameter; path is the pathname of the temporary file (either the root 
directory of the specified drive or the directory specified in the TEMP 
environment variable); prefiz is all the letters (up to the first Ea es the 
string pointed to by the lpPrefizString parameter; and uuuu is the hexa- 
decimal value of the number specified by the wUnique parameter. 


Parameter Type/Description 


cDriveL etter BYTE Specifies the suggested drive for the tem- 
porary filename. If cDriveLetter is zero, the default 
drive is used. 


lpPrefizString LPSTR Points to a null-terminated character 
string to be used as the temporary filename prefix. 


wUnique WORD Specifies an unsigned short integer. 


loTempFileName LPSTR Points to the buffer that is to receive the 
temporary filename. 


Return Value 


The return value specifies a unique numeric value used in the temporary 
filename. If a nonzero value was given for the wUnique parameter, the 
return value specifies this same number. 


Comments 


The GetTempFileName function uses the suggested drive letter for 
creating the temporary filename, except in the following cases: 


e Ifa hard disk is present, GetTempFileName always uses the 
drive letter of the first hard disk. 


e If aTEMP environment variable is defined and its value begins 
with a drive letter, that drive letter is used. 


If the TF. FORCEDRIVE bit of the cDriveLetter parameter is set, the 
above exceptions do not apply. The temporary filename will always be 
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created in the current directory of the drive specified by cDrivel etter, 
regardless of the presence of a hard disk or the TEMP environment 
variable. 


If the wUnique parameter is zero, Get TempFileName attempts to form 
a unique number based on the current system time. If a file with the 
resulting filename exists, the number is increased by one and the test for 
existence is repeated. This continues until a unique filename 1s found; 
GetTempFileName then creates a file by that name and closes it. No 
attempt is made to create and open the file when wUnique is nonzero. 


WORD GetTextAlign(hDC) 


This function retrieves the status of the text-alignment flag. The text- 
alignment flag determines how the TextOut function aligns a string of 
text in relation to the string’s starting point. 


Parameter Type/Description 
hDC HDC Identifies the device context. 10? =) 
Cal pipe : 
BAIR IRE forme NS | 
Return Value Rgiiabe | a aia 
Cee 


The return value specifies the status of the text-alignment flag. The return 
value is a combination of one or more of the following values: 


TA_ BASELINE Specifies alignment of the z-axis and the baseline 
of the chosen font within the bounding rectangle. 

TA~ BOTTOM Specifies alignment of the z-axis and the bottom 
of the bounding rectangle. 

TA_ CENTER Specifies alignment of the y-axis and the center of 
the bounding rectangle. 

TA LEFT Specifies alignment of the yaxis and the left side 


of the bounding rectangle. 
TA_ NOUPDATECP _ Specifies that the current position is not updated. 


TA~ RIGHT Specifies alignment of the y-axis and the right 
side of the bounding rectangle. 

TA_ TOP Specifies alignment of the z-axis and the top of 
the bounding rectangle. 

TA~ UPDATECP Specifies that the current position 1s updated. 
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Comments 


To determine if a particular flag is set, apply the bitwise AND operator to 
the return value. The return value is zero if the status flag was not set. 


short GetTextCharExtra(hDC) 

This function retrieves the current intercharacter spacing. The interchar- 
acter spacing defines the extra space (in logical ea that the TextOut 
function adds to each character as it writes a line. The spacing is used to 
expand lines of text. 


If the current mapping mode is not MM_ TEXT, the Get TextCharExtra 
function transforms and rounds the result to the nearest unit. 


Parameter | Type/ Description 


ADC HDC Identifies the device context. 


Return Value 


The return value specifies the current intercharacter spacing. 


DWORD GetTextColor(hDC) 


This function retrieves the current text color. The text color defines the 
foreground color of characters drawn by using the TextOut function. 


Parameter Type/Description 
hDC HDC Identifies the device context. 


Return Value 


The return value specifies the current text color as an RGB color value. 


DWORD GetTextExtent(hDC, IpString, nCount) 


This function computes the width and height of the line of text pointed to 
by the lpString parameter. The Get TextExtent function uses the cur- 
rently selected font to compute the dimensions of the string. The width 
and height (in logical units) are computed without considering the current 
clipping region. 
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Parameter Type/Description 

hDC HDC Identifies the device context. 

lpString LPSTR Points to a text string. 

nCount short Specifies the number of characters in the text 
string. 


Return Value 


The return value specifies the dimensions of the string. The height is in the 
high-order word; the width is in the low-order word. 


Comments 


Since some devices do not place characters in regular cell arrays (that is, 
they carry out kerning), the sum of the extents of the characters in a 
string may not be equal to the extent of the string. 


short GetTextFace(hDC, nCount, lpFacename) 


This function copies the typeface name of the selected font into a buffer 
pointed to by the /pFacename parameter. The typeface name is copied as 
a null-terminated character string. The nCount parameter specifies the 
maximum number of characters to be copied. If the name is longer than 
the number of characters specified by nCount, it is truncated. 


Parameter Type/Description 

hDC HANDLE | Identifies the device context. 

nCount | short Specifies the size of the buffer in bytes. 
lpFacename LPSTR Points to the buffer that is to receive the 


typeface name. 


Return Value 


The return value specifies the actual number of bytes copied to the buffer. 
It is zero if an error occurs. 


BOOL GetTextMetrics(hDC, IpMetrics) 


This function fills the buffer pointed to by the /pMetrics parameter with 
the metrics for the selected font. 
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Parameter Type/Description 
hDC HDC Identifies the device context. 
lpMetrics LPTEXTMETRIC Points to the TEXTMETRIC 
data structure that is to receive the metrics. a 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
function is successful. Otherwise, it is zero. 


LPINT GetThresholdEvent( ) 

This function retrieves a flag that identifies a recent threshold event. A 
threshold event is any transition of a voice queue from nto n — 1 where 
nis the threshold level in notes. 


This function has no parameters. 


Return Value 


The return value points to a short integer that specifies a threshold event. 


int GetThresholdStatus( ) 

This function retrieves the threshold-event status for each voice. Each 
bit in the status represents a voice. If a bit is set, the voice-queue level 
is currently below threshold. 

The GetThresholdStatus function also clears the threshold-event flag. 
This function has no parameters. 


Return Value 


The return value specifies the status flags of the current threshold event. 
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DWORD GetTickCount( ) 


This function obtains the number of milliseconds that have elapsed 
since the system was started. 


This function has no parameters. 


Return Value 


The return value specifies the number of milliseconds that have elapsed 
since the system was started. 


Comments 


The count is accurate within +55 milliseconds. 


HWND Get TopWindow(h Wnd) 


This function searches for a handle to the top-level child window that 
belongs to the parent window associated with the hWnd parameter. If 
the window has no children, this function returns NULL. 


Parameter Type/Description 
hWnd HWND Identifies the parent window. 


Return Value 


The return value identifies a handle to the top-level child window in a 
parent window’s linked list of child windows. If no child windows exist, 
it is NULL. 


BOOL GetUpdateRect(hWnd, IpRect, bErase) 


This function retrieves the coordinates of the smallest rectangle that 
completely encloses the update region of the given window. The 
GetUpdateRect function gives the rectangle in client coordinates. If 
there is no update region, GetUpdateRect makes the rectangle empty 
(sets all coordinates to zero). 


The bErase parameter specifies whether GetUpdateRect should erase the 
background of the update region. If bErase is TRUE and the update region 
is not empty, the background is erased. To erase the background, Get- 

UpdateRect sends a WM ERASEBICGND message to the given window. 
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Parameter Type/Description 

hWnd HWND Identifies the window whose update region 1s 
to be retrieved. 

loRect LPRECT Points to the RECT data structure that 
is to receive the client coordinates of the enclosing rect- 
angle. 

bErase BOOL Specifies whether the background in the 


update region is to be erased. 


Return Value 


The return value specifies the status of the update region of the given win- 
dow. It is nonzero if the update region is not empty. Otherwise, it 1s zero. 


Comments 


The update rectangle retrieved by the BeginPaint function is identical to 
that retrieved by the GetUpdateRect function. 


BeginPaint automatically validates the update region, so any call to 


GetUpdateRect made immediately after the BeginPaint call retrieves 
an empty update region. 


int GetUpdateRgn(hWnd, hRgn, fErase) 
This function copies a window’s update region into a region identified by 


the hRgn parameter. The coordinates of this region are relative to the 
upper-left corner of the window (client coordinates). 


Parameter Type/Description 


hWnd HWND Identifies the window that contains the 
region to be updated. 

hRgn HRGN Identifies the update region. 

fErase BOOL § Specifies whether or not the window back- 


ground should be erased and non-client areas of child 
windows should be drawn. If it is zero, no drawing 1s 
done. 
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Return Value 


The return value specifies a short-integer flag that indicates the type of 
resulting region. It can be any one of the following values: 


COMPLEXREGION The region has overlapping borders. 
ERROR No region was created. 

NULLREGION The region is empty. 

SIMPLEREGION The region has no overlapping borders. 


WORD GetVersion( ) 

This function returns the current version number of Windows. 

This function has no parameters. 

Return Value 

The return value specifies the major and minor version numbers of Win- 


dows. The high-order byte specifies the minor version (revision) number; 
the low-order byte specifies the major version number. 


DWORD GetViewportExt(hDC) 


This function retrieves the z and extents of the device context’s 
viewport. 


Parameter Type/Description 
hDC HDC Identifies the device context. 


Return Value 


The return value specifies the a and yextents (in device units). The 
y-extent is in the high-order word; the extent is in the low-order word. 
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DWORD GetViewportOrg(hDC) 


This function retrieves the a- and y-coordinates of the origin of the 
viewport associated with the specified device context. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


Return Value 


The return value specifies the origin of the viewport (in device coordi- 
nates). The ycoordinate is in the high-order word; the zcoordinate 1s 
in the low-order word. 


HWND GetWindow(hWnd, wCmd) 


This function searches for a handle to a window from the window-man- 
ager’s list. The window-manager’s list contains entries for all top-level 
windows, their associated child windows, and the child windows of any 
child windows. The wCmd parameter specifies the relationship between 
the window identified by the hWnd parameter and the window whose 
handle is returned. 


Parameter Type/Description 


hWnd HWND Identifies the original window. 


wC'md WORD Specifies the relationship between the orig)- 
~ nal window and the returned window. It may be one of 
the following values: 


Value Meaning 
GW. CHILD Identifies the window’s child 
window. 


GW_HWNDFIRST Returns the first sibling window 
for a child window; otherwise, it 
returns the first top-level window 
in the list. 


GW-HWNDLAST ~ Returns the last sibling window 
for a child window; otherwise, it 
returns the last top-level window 
in the list. 
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GW. HWNDNEXT Returns the window that follows 
the given window on the window- 
manager’s list. 


GW_HWNDPREV _— Returns the previous window on 


the window-manager’s list. 
GW_ OWNER Identifies the window’s owner. | 
Return Value 


The return value identifies a window. 


HDC GetWindowDC(h Wnd) 


This function retrieves the display context for the entire window, includ- 
ing caption bar, menus, and scroll bars. A window display context permits 
painting anywhere in a window, including the caption bar, menus, and 
scroll bars, since the origin of the context is the upper-left corner of the 
window instead of the client area. 


Get WindowDC assigns default attributes to the display context each 
time it retrieves the context. Previous attributes are lost. 


Parameter Type/Description 


hWnd HWND Identifies the window whose display context 
is to be retrieved. 


Return Value | 


The return value identifies the display context for the given window if the 
function is successful. Otherwise, it is NULL. 


Comments 


The GetWindowDC function is intended to be used for special painting 
effects within a window’s non-client area. Painting in non-client areas of 
any window is not recommended. 


The GetSystemMetrics function can be used to retrieve the dimensions 
of various parts of the non-client area, such as the caption bar, menu, and 
scroll bars. 


After painting is complete, the ReleaseDC function must be called to 


release the display context. Failure to release a window display context 
may have serious effects on painting requested by other applications. 


317 


Get WindowExt 


DWORD GetWindowExt(hDC) 


This function retrieves the and yextents of the window associated with 
the specified device context. 


Parameter Type/Description 
ADC HDC | Identifies the device context. 


Return Value 


The return value specifies the » and yextents (in logical units). The 
y-extent is in the high-order word; the a-extent is in the low-order word. 


LONG GetWindowLong(hWnd, nIndez) 


This function retrieves information about the window identified by the 
hWnd parameter. 


Parameter Type/Description 
hWnd HWND Identifies the window. 
nindex int Specifies the value to be retrieved. It must be one 


of the following values: 


Value Meaning 

GWL_ STYLE Window style 

GWL-~ WNDPROC _ Long pointer to the window 
function 


Return Value 


The return value specifies information about the given window. 
Comments 
To access any extra four-byte values that were allocated when the 


window-class structure was created, use positive offsets as indexes, 
starting at zero for the first four-byte value of the extra space. 
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DWORD GetWindowOrg(hDC) 


This function retrieves the # and ycoordinates of the origin of the win- 
dow associated with the specified device context. 


Parameter Type/ Description 
hDC HDC Identifies the device context. 


Return Value 


The return value specifies the origin of the window (in logical coordinates). 
The y coordinate is in the high-order word; the xcoordinate is in the low- 
order word. 


void GetWindowRect(hWnd, lpRect) 


This function copies the dimensions of the bounding rectangle of the 
specified window into the structure pointed to by the IpRect parameter. 
The dimensions are given in screen coordinates, relative to the upper-left 
corner of the display screen, and include the caption, border, and scroll 
bars, if present. 


Parameter Type/Description 
hWnd HWNOD _sIdentifies the window. 
lpRect LPRECT Points toa RECT data structure that 


contains the screen coordinates of the upper-left and 
lower-right corners of the window. 


Return Value 


None 


HANDLE GetWindowTask(hWnd) 


This function searches for the handle of a task associated with the hWnd 
parameter. A task is any program that executes as an independent unit. 
All 5 eecaaae are executed as tasks. Each instance of an application is 
a task. 
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Parameter Type/Description 


hWnd HWND Identifies the window for which a task han- 


dle is retrieved. 


Return Value 


The return value identifies the task associated with a particular window. 


int GetWindowText(hWnd, IpString, nMazCount) 


This function copies the given window’s caption title (if it has one) into 
the buffer pointed to by the lpString parameter. If the hWnd parameter 
identifies a control, the GetWindowText function copies the text within 
the control instead of copying the caption. 


Parameter Type/Description 


hWnd HWND Identifies the window or control whose cap- 
tion or text is to be copied. 
loString LPSTR Points to the buffer that is to receive the 


copied string. 


nMazCount int Specifies the maximum number of characters to 
be copied to the buffer. If the string is longer than the 
number of characters specified in the nMazCount 
parameter, it is truncated. 


Return Value 


The return value specifies the length of the copied string. It is zero if the 
window has no caption. 


Comments 


This function causes a WM. GETTEXT message to be sent to the given 
window or control. 
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int GetWindow TextLength(h Wnd) 

This function returns the length of the given window’s caption title. If 
the hWnd parameter identifies a control, the GetWindowTextLength 
function returns the length of the text within the control instead of the 
caption. 


Parameter Type/Description 


hWnd HWND Identifies the window or control. 


Return Value 


The return value specifies the text length. It 1s zero if no such text exists. 


WORD GetWindowWord(hWnd, nIndez) 


This function retrieves information about the window identified by hWnd. 


Parameter Type/Description 
hWnd HWND _ Identifies the window. 
nindex int Specifies the word to be retrieved. It must be one 


of the following values: 
Value Meaning 


GWW-_ HINSTANCE 
Instance handle of the module 
that owns the window. 


GWW_HWNDPARENT 
Handle of the parent window, 
if any. 


GWW_HWNDTEXT 


Handle to the window title. 


GWW_L ID Control ID of the child window. 


Return Value 


The return value specifies information about the given window. 
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Comments 


To access any extra two-byte values that were allocated when the 
window-class structure was created, use positive offsets as indexes, 
starting at zero for the first two-byte value of the extra space. 


ATOM GlobalAddAtom(IpString) 


This function adds the character string pointed to by the [pString 
parameter to the atom table and creates a new global atom that 
uniquely identifies the string. A global atom is an atom that is avail- 
able to all applications. The atom can be used in a subsequent 
a a function to retrieve the string from the atom 
table. 


The GlobalAddAtom function stores no more than one copy of a given 
string in the atom table. If the string is already in the table, the function 
returns the existing atom value and increases the string’s reference count 
by one. The string’s reference count is a number that specifies the number 
of times GlobalAddAtom has been called for a particular string. 


Parameter Type/Description 


lpString LPSTR Points to the character string to be added to 
the table. The string must be a null-terminated charac- 
ter string. 


Return Value 


The return value identifies the newly created atom if the function 1s suc- 
cessful. Otherwise, it is NULL. 


Comments 


The atom values returned by GlobalAddAtom are in the range C000 to 
FFFF (hexadecimal). 


HANDLE GlobalAlloc(wFlags, dwBytes) 


This function allocates the number of bytes of memory specified by oe 
the dwBytes parameter from the global heap. The memory can be fixed 
or movable, depending on the memory type specified by the wFlags 
parameter. | 
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Parameter Type/Description 


WORD Specifies one or more flags that tell the 
GlobalAlloc function how to allocate the memory. 


wklags 


It can be one or more of the following values: 


Value 
GMEM_ DDESHARE 


GMEML_ DISCARDABLE 


GMEM_ FIXED 
GMEM_ NOT_ BANKED 


GMEM_ MOVEABLE 


GMEM_ NOCOMPACT 


GMEM_ NODISCARD 


Meaning 


Allocates sharable 
memory. This is used for 
dynamic data exchange 


(DDE 


Allocates discardable 
memory. Can only 

be used with 

GMEM_ MOVEABLE. 


Allocates fixed memory. 


Allocates non-banked 
memory (see the descrip- 
tion of non-banked 
memory provided in the 
readme file that was 
shipped with the Micro- 
soft Windows 2.0 SDK). 
Cannot be used with 


GMEM_ NOTIFY. 


Allocates movable 
memory. Cannot be used 


with GMEM_ FIXED. 


Does not compact or dis- 
card to satisfy the alloca- 
tion request. 


Does not discard to 
satisfy the allocation 
request. 
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GMEM_ NOTIFY Calls the notification rou- 
tine if memory is about to 
be discarded. 


GMEM_ ZEROINIT Initializes memory con- 


tents to zero. 


Choose GMEM_ FIXED 
or GMEM_ MOVEABLE, 
and then combine others 
as needed by using the 
bitwise OR operator. 


dwBytes DWORD Specifies the number of bytes to be 
allocated. 


Return Value 


The return value identifies the allocated global memory if the function is 
successful. Otherwise, it is NULL. 


DWORD GlobalCompact(dwMinFree) 


This function generates the number of free bytes of global memory 
specified by the dwMinF ree parameter by compacting and, if necessary, 
discarding from the system’s global heap. The function checks the global 
heap for a number of contiguous free bytes equal to that specified by the 
dwMinF ree parameter. If the bytes do not exist, the GlobalCompact 
function compacts memory. If this does not generate the requested amount 
of space, the function discards unlocked discardable blocks until the 
requested space is generated. 


Parameter Type/ Description 


dwMinF ree DWORD Specifies the number of free bytes desired. 


Return Value 


The return value specifies the number of bytes in the largest block of free 
global memory. 


Comments 
If dwMinF ree is zero, the return value specifies the number of bytes in the 


largest free segment that Windows can generate if it removes all discard- 
able segments and then compacts memory. 
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If an application uses the return value as the wk lags parameter 
to the GlobalAlloc function, the GMEM_.NOCOMPACT or 
GMEM_ NODISCARD flags cannot be used. 


ATOM GlobalDeleteAtom(nAtom) 


This function deletes a global atom and, if the atom’s reference count is 
zero, removes the associated string from the atom table. (A global atom is 
an atom that is available to all Windows applications.) 


An atom’s reference count specifies the number of times the atom has been 
added to the atom table. The GlobalAddAtom function increases the 
count on each call; the GlobalDeleteAtom function decreases the count 
on each call. GlobalDeleteAtom removes the string only if the atom’s 
reference count is zero. 


Parameter Type/Description 
nAtom ATOM Identifies the atom and character string to be 
deleted. 


Return Value 
The return value specifies the outcome of the function. It is NULL if the 


function is successful. It is equal to nAtom if the function failed and the 
atom has not been deleted. 


HANDLE GlobalDiscard(iMem) 


This function discards a global memory block specified by the hMem 
parameter. 


Parameter Type/ Description 
hMem HANDLE Identifies the global memory block to be 
discarded. 


Return Value 


The return value identifies the discarded block if the function is successful. 
Otherwise, it is zero. 
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Comments 

G@MEM~ DISCARDA BLE 
The GlobalDiscard function discards only global objects that an applica- 
tion allocated with the GMEM=_BISCARDED and GMEM_ MOVEABLE 
flags set. The function fails if an application attempts to discard a fixed 
object. 


ATOM GlobalFindAtom (IpString) 


This function searches the atom table for the character string pointed to 
by the lpString parameter and retrieves the global atom associated with 
that string. (A global atom is an atom that is available to all Windows 
applications.) 


Parameter Type/Description 

lpString LPSTR Points to the character string to be searched 
for. The string must be a null-terminated character 
string. 


Return Value 


The return value identifies the global atom associated with the given 
string. It is NULL if the string is not in the table. 


WORD GlobalFlags(hMem) 


This function returns information about the global memory block specified 
by the hMem parameter. 


Parameter Type/Description 
hMem HANDLE Identifies the global memory block. 


Return Value 


The return value specifies a memory-allocation flag in the high byte. The 
flag ey a one of the following values if memory identified by hMem is 
iscarded: 
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GMEM_ DISCARDED The block has been discarded. 
GMEM_ DISCARDABLE The block can be discarded. 
GMEM_ NOT_ BANKED The block cannot be banked. 
GMEM_ DDESHARE The block can be shared. 


Comments 
The low byte of the return value contains the reference count of the block. 


The GMEMW LOCKCOUNT mask may be used to retrieve the lock-count 
value from the return value. 


HANDLE GlobalFree(hMem) 


This function frees the global memory block identified by the hMem 
parameter. 


Parameter Type/ Description 
hMem HANDLE _ Identifies the global memory block to be 
freed. 


Return Value 


The return value identifies the outcome of the function. It is NULL if the 
function is successful. Otherwise, it is equal to hMem. 


Comments 


The GlobalF ree function must not be used to free a locked memory 
oe The block must first be unlocked by using the GlobalUnlock 
unction. 


WORD GlobalGetAtomName(nAtom, lpBuffer, nSize) 


This function retrieves a copy of the character string associated with the 

nAtom parameter and places it in the buffer pointed to by the lpBuffer 
arameter. The nSize parameter specifies the maximum size of the buffer. 
A global atom is an atom that is available to all Windows applications. ) 
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Parameter Type/Description 

nAtom ATOM Identifies the character string to be retrieved. 

loBuffer LPSTR Points to the buffer that is to receive the 
character string. 

nSize int Specifies the maximum size (in bytes) of the 
buffer. 


Return Value 


The return value specifies the actual number of bytes copied to the buffer. 
It is zero if the specified global atom is not valid. 


DWORD GlobalHandle(wifem) 


This function retrieves the handle of the global memory object whose seg- 
ment address is specified by the wMfem parameter. 


Parameter Type/Description 


wMem WORD Specifies an unsigned integer value that gives 
the segment address of a global memory object. 


Return Value 


The low-order word of the return value specifies the handle of the global 
memory object. The high-order word of the return value specifies the seg- 
ment address of the memory object. 


LPSTR GlobalLock(hMem) 


This function retrieves the absolute memory address of the global memory 
block specified by the hMem parameter. The block is locked into memory 
at the given address and its reference count is increased by one. Locked 
memory is not subject to moving or discarding. 


The block remains locked in memory until its reference count is decreased 
to zero by using the GlobalUnlock function. 


Parameter Type/Description 
hMem HANDLE Identifies the global memory block to be 
locked. 
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- Return Value 


The return value points to the first byte of memory in the global block 
if the function is successful. If the object has been discarded or an error 
occurs, the return value is NULL. 


Comments 


Discarded objects always have a reference count of zero. 


HANDLE GlobalReAlloc(hMem, dwBytes, wFlags) 


This function reallocates the global memory block specified by the hMem 
parameter by increasing or decreasing its size to the number of bytes 
specified by the dwBytes parameter. 


Parameter Type/Description 

hMem HANDLE | Identifies the global memory block to be 
reallocated. 

dwBytes DWORD Specifies the new size of the memory block. 

wk lags WORD | Specifies how to reallocate the global block. 


If the existing memory flags can be modified, use either 
one or both of the following flags (if both flags are 
specified, join them with the bitwise OR operator): 


Value Meaning 

GMEM_ DISCARDABLE 
Memory can be discarded. Use 
only with GMEM_ MODIFY. 


GMEM_ MODIFY Memory flags are modified. The 
dwBytes parameter is ignored. 
Use only if an application will 
modify existing memory flags and 
not reallocate the memory block 
with a new size. 
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GMEM.. MOVEABLE: 


Memory is movable. If dwBytes is 
zero, this flag causes a previously 
movable object to be discarded 
(if the block’s reference count is 
oo) If dwBytes is nonzero and 
the block specified by hMem 1s 
fixed, this flag allows the reallo- 
cated block to be moved toa 
new fixed location. (Note that 
the handle returned by the 
GlobalReAlloc function in 

this case may be different from 
the handle passed to the 
function.) Use this flag with 
GMEM_ MODIFY to make a 
fixed memory block movable. 


GMEM_ NOCOMPACT 


Memory will not be compacted or 
discarded in order to satisfy the 
allocation request. This flag is 
ignored if the GMEM_~ MODIFY 
flag is set. 


GMEM_ NODISCARD 


GMEM_ ZEROINIT 


Return Value 


Objects will not be discarded in 
order to satisfy the allocation 
request. This flag is ignored if the 
GMEMW MODIF’'Y flag is set. 


If the block is growing, the addi- 
tional memory contents are inl- 
tialized to zero. This flag is 
ignored if the GMEM_ MODIFY 


flag is set. 


The return value identifies the reallocated global memory if the function 
is successful. The return value is NULL if the block cannot be reallocated. 


The return value is always identical to the hMem parameter, unless the 
GMEM~ MOVEABLE flag is used to allow movement of a fixed block to 


a new fixed location. 
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DWORD GlobalSize(hMem) 


This function retrieves the current size (in bytes) of the global memory 
block specified by the hMem parameter. 


Parameter Type/Description 


hMem HANDLE Identifies the global memory block. 


Return Value 


The return value specifies the size (in bytes) of the specified memory block. 
It is zero if the given handle is not valid. 


Comments 


The actual size of a memory block is sometimes larger than the size 
requested when the memory was allocated. 


An apphication should call the GlobalF lags function prior to calling the 
GlobalSize function in order to verify that the specified memory block 
was not discarded. If the memory block were discarded, the return value 
for GlobalSize would be meaningless. 


BOOL GlobalUnlock(hMem) 


This function unlocks the global memory block specified by the hMem 
parameter and decreases the block’s reference count by one. The block is 
completely unlocked, and subject to moving or discarding, if the reference 
count is decreased to zero. 


Parameter Type/Description 
hMem HANDLE Identifies the global memory block to be 
unlocked. 


Return Value 
The return value specifies the outcome of the function. It is zero if the 


block’s reference count was decreased to zero. Otherwise, the return value 
is NONZETO. 
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void GlobalUnWire(hMem) 


This function unlocks a memory segment that was locked by the 
GlobalWire function and sets the lock count to zero. 


Parameter Type/ Description 


hMem HMEM Identifies the segment that will be unlocked. 


Return Value 


None 


LPSTR GlobalWire(hMem) 


This function moves a segment into low memory and locks it—a procedure 
that is extremely useful if an application must lock a segment for a long 
period of time. If a segment from the middle portion of memory is locked 
for a long period of time, it causes memory-management problems by 
reducing the size of the largest, contiguous available block of memory. The 
Global Wire function moves a segment to the lowest possible address in 
aaa and locks it, thereby freeing the memory area Windows uses most 
oiten. 


Parameter Type/ Description 
hMem HMEM Identifies the segment that will be moved 
and locked. 


Return Value 


The return value points to the new segment location. 


BOOL GrayString(hDC, hBrush, lpOutputFunc, IpData, nCount, 
X, Y, nWidth, nHeight) 


This function draws gray text at the given location. The GrayString 
function draws gray text by writing the text in a memory bitmap, graying 
the bitmap, and then copying the bitmap to the display. The function 
grays the text regardless of the selected brush and background. Gray- 
String uses the system font regardless of the selected font, unless given an 
application-supplied function that explicitly changes the font. 
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If the lpOutputF'unc parameter is NULL, GDI uses the TextOut function, 
and the /pData parameter is assumed to be a long pointer to the character 
string to be output. If the characters to be output cannot be handled by 
TextOut (for example, the string is stored as a bitmap), the application 
must supply its own output function. 


Parameter - Type/Description 

hDC HDC Identifies the device context. 

hBrush HBRUSH Identifies the brush to be used for 
graying. 


lpOutputF unc FARPROC Is the procedure-instance address of the 
application-supplied function that will draw the string, 
or, if the TextOut function is to be used to draw the 
string, it is a NULL pointer. See the following “Com- 
ments” section for details. 


lpData DWORD Specifies a long pointer to data to be 
passed to the output function. If the lpOutputFunc 
parameter is NULL, /pData must be a long pointer to 
the string to be output. 


nCount int Specifies the number of characters to be output. If 
the nCount parameter is zero, GrayString calculates 
the length of the string (assuming that lpData is a 
pointer to the string). If nCount is -1 and the function 
pointed to by lpOutputFunc returns zero, the image is 
shown but not grayed. . 


xX int Specifies the logical xcoordinate of the starting 
position of the rectangle that encloses the string. 


int Specifies the logical ycoordinate of the starting 
position of the rectangle that encloses the string. 


nWidth int Specifies the width (in logical units) of the rectan- 
gle that encloses the string. If the n Width parameter is 
zero, GrayString calculates the width of the area, 
assuming /pData is a pointer to the string. 


nHeight int Specifies the height (in logical units) of the rec- 
tangle that encloses the string. If the nHeight parameter 
is zero, GrayString calculates the height of the area, 
assuming IpData is a pointer to the string. 
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Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
string is drawn. A return value of zero means that either the TextOut 
function or the application-supplied output function returned zero, or 
there was insufficient memory to create a memory bitmap for graying. 


Comments 


The callback function must use the Pascal calling convention and must be 
declared FAR. The callback function must have the following form: 


BOOL FAR PASCAL OutputFunc(hDC, lpData, nCount) 
HDC ;DC; 
DWORD IpData; 


int nCount; 


OutputF unc is a placeholder for the application-supplied callback func- 
tion name. The actual name must be exported by including it in an 
EXPORTS statement in the application’s module-definition file. 


Parameter Description 


hDC Identifies a memory device context with a bitmap of at 
least the width and height specified by the nWidth and 
nHeight parameters, respectively. 


lpData Points to the character string to be drawn. 


nCount Specifies the number of characters to be output. 


Return Value 


The return value must be nonzero to indicate success. Otherwise, it is 
Zero. 


Comments 


This output function (OutputFunc) must draw an image relative 
to the coordinates (0,0) rather than (X, Y). The address passed 

as the lpOutputFunc parameter must be created by using the 
MakeProcInstance function, and the output function name must 
be exported; it must be explicitly defined in an EXPORTS state- 
ment of the application’s module-definition file. 


The MM... TEXT mapping mode must be selected before using this 
function. 
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BYTE HIBYTE(n/nteger) 


This function retrieves the high-order byte from the integer value specified 
by the nl/nteger parameter. 


Parameter Type/Description 
ninteger int Specifies the value to be converted. 


Return Value 


The return value specifies the high-order byte of the given value. 


void HideCaret(hWnd) 


This function hides the system caret by removing it from the display 
screen. Although the caret is no longer visible, it can be displayed again 
by using the ShowCaret function. Hiding the caret does not destroy 
its current shape. 


The HideCaret function hides the caret only if the given window owns 
the caret. If the hWnd parameter is NULL, the function hides the caret 
only if a window in the current task owns the caret. 


Hiding is accumulative. If HideCaret has been called five times in a row, 
ShowCaret must be called five times before the caret will be shown. 


Parameter Type/Description 
hWnd HWND Identifies the window that owns the system 


caret, or is NULL to indirectly specify the window in 
the current task that owns the caret. 


Return Value 


None 


BOOL HiliteMenultem(hWnd, hMenu, wlDHiliteltem, wHilite) 
This function highlights or removes the highlighting from a top-level 


(menu-bar) menu item. A menu is highlighted when it is displayed in 
inverse video (on a monochrome display). 
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Parameter Type/Description 
hWnd HWND Identifies the window that contains the 
menu. 
hMenu HMENU | Identifies the top-level menu that contains won 


the item to be highlighted. 


wlDHAiliteltem WORD Specifies the integer identifier of the menu 
item or the offset of the menu item in the menu, 
depending on the value of the wHilste parameter. 


wHilite WORD Specifies whether the menu item is high- 
lighted or the highlight is removed. It can be a combi- 
nation of MF_ HILITE or MF_ UNHILITE with 
MF. BYCOMMAND or MF_ BYPOSITION. The values 
can be combined using the bitwise OR operator. These 
values have the following meanings: 


Value Meaning 


MF. BYCOMMAND Interprets wlDHiliteltem as the 
menu-item ID (the default 


interpretation). 

MF. BYPOSITION Interprets wlDHiliteltem as an 
offset. 

MF HILITE Highlights the item. If this 


value is not given, highlighting 
is removed from the item. 


MF_ UNHILITE Removes highlighting from the 


item. 


Return Value 


The return value specifies whether or not the menu item is highlighted. It 
is nonzero if the item is highlighted. Otherwise, it is zero. 


Comments 


The MF_ HILITE and MF_ UNHILITE flags can be used only with the 
HiliteMenultem function; they cannot be used with the ChangeMenu 
function. 
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WORD HIWORD(lInteger) 


This macro retrieves the high-order word from the long-integer value 
specified by the U/nteger parameter. 


Parameter Type/Description 
Integer long Specifies the value to be converted. 


Return Value 


The return value specifies the high-order word of the given long-integer 
value. 
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void InflateRect(/pRect, X, Y) 


This function increases or decreases the width and height of the specified 
rectangle. The InflateRect function adds X units to the left and right 
ends of the rectangle, and adds Y units to the top and bottom. The X and 
Y parameters are signed values: positive values increase the width and 
height, and negative values decrease them. 


Parameter Type/Description 

lpRect LPRECT Points to the RECT data structure to be 
modified. 

X int Specifies the amount to increase or decrease the 
rectangle width. It must be negative to decrease the 
width. 

Y int Specifies the amount to increase or decrease the 
rectangle height. It must be negative to decrease the 
height. 


Return Value 


None 


Comments 


The coordinate values of a rectangle must not be greater than 32,767 units 
or less than —32,768 units. The X and Y parameters must be chosen care- 
fully to prevent invalid rectangles. 


BOOL InitAtomTable(n5%ze) 


This function initializes an atom hash table and sets its size to that 
specified by the nSize parameter. If this function is not called, the atom 
hash table size is set to 37 by default, limiting the maximum number of 
atoms to 37. 


If used, this function should be called before any other atom-manager 
function. 


Parameter Type/Description 
nSize int Specifies the size a table entries) of the atom 
hash table. This value should be a prime number. 
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Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
function is successful. Otherwise, it is zero. 


BOOL InSendMessage( ) 


This function specifies whether the current window function is process- 
ing a message that is passed to it through a call to the SendMessage 
function. 


This function has no parameters. 


Return Value 


The return value specifies the outcome of the function. It is TRUE if the 
window function is processing a message sent to it with SendMessage. 


Otherwise, it is FALSE. 


Comments 


Applications use the InSendMessage function to determine how to han- 
dle errors that occur when an inactive window processes messages. For 
example, if the active window uses SendMessage to send a request for 
information to another window, the other window cannot become active 
until it returns control from the SendMessage call. The only method 

an inactive window has to inform the user of an error is to create a mes- 
sage box. 


short IntersectClipRect(hDC, X1, Y1, X2, Y2) 


This function creates a new clipping region by forming the intersection of 
the current region and the rectangle specified by X1, Y1, X2, and Y2. GDI 
clips all subsequent output to fit within the new boundary. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


XI | short Specifies the logical coordinate of the upper- 
left corner of the rectangle. 


Y1 short Specifies the logical y-coordinate of the upper- 
left corner of the rectangle. 
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X2 short Specifies the logical +coordinate of the lower- 
right corner of the rectangle. 


Y2 short Specifies the logical ycoordinate of the lower- 
right corner of the rectangle. 


Return Value 


The return value specifies the new clipping region’s type. It can be any one 
of the following values: 


Value Meaning 

COMPLEXREGION New clipping region has overlapping 
borders. 

ERROR Device context is not valid. 

NULLREGION New clipping region is empty. 

SIMPLEREGION New clipping region has no overlapping 
borders. 

Comments 


The width of the rectangle, specified by the absolute value of X2 — X/, 
must not exceed 32,767 units. This limit applies to the height of the 
rectangle as well. 


int IntersectRect(IpDestRect, lpSre1Rect, IlpSrc2Rect) 


This function creates the intersection of two existing rectangles. The 
intersection is the largest rectangle contained in both rectangles. The 
IntersectRect function copies the new rectangle to the RECT data 
structure pointed to by the lpDestRect parameter. 


Parameter Type/Description 

lpDestRect LPRECT Points to the RECT data structure that 
is to receive the intersection. 

loSrc1Rect LPRECT Points toa RECT data structure that 
contains a source rectangle. 

lpSrc2Rect LPRECT Points toa RECT data structure that 


contains a source rectangle. 
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Return Value 


The return value specifies the intersection of two rectangles. It is nonzero 
if the intersection of the two rectangles is not empty. It is zero if the inter- 
section 1s empty. 


void InvalidateRect(hWnd, lpRect, bErase) 


This function invalidates the client area within the given rectangle by 
adding that rectangle to the window’s update region. The invalidated 
rectangle, along with all other areas in the update region, is marked 

for painting when the next WM_ PAINT message occurs. The invalidated 
areas accumulate in the update region until the region is processed when 
the next WM_ PAINT message occurs, or the region is validated by using 
the ValidateRect or ValidateRgn function. 


The b£rase parameter specifies whether the background within the update 
area is to be erased when the update region is processed. If bErase is non- 
zero, the background is erased when the BeginPaint function is called; if 
bErase is zero, the background remains unchanged. If bErase is nonzero 
for any part of the update region, the background in the entire region is 
erased, not just in the given part. 


Parameter Type/Description 


hWnd HWND Identifies the window whose update region is 
to be modified. 
lnRect LPRECT Points toa RECT data structure that 


contains the rectangle (in client coordinates) to be 
added to the update region. If the /pRect parameter is 
NULL, the entire client area is added to the region. 


bErase BOOL = Specifies whether the background within the 
update region is to be erased. 


Return Value 

None 

Comments 

Windows sends a WM_ PAINT message to a window whenever its update 


region is not empty and there are no other messages in the application 
queue for that window. 
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void InvalidateRgn(hWnd, hRgn, bErase) 


This function invalidates the client area within the given region by add- 
ing it to the current update region of the given window. The invalidated 
region, along with all other areas in the update region, is marked for 
painting when the next WM_PAINT message occurs. ‘The invalidated 
areas accumulate in the update region until the region is processed when 
the next WM_PAINT message occurs, or the region is validated by using 
the ValidateRect or ValidateRgn function. 


The bErase parameter specifies whether the background within the update 
area is to be erased when the update region is processed. If bErase is non- 
zero, the background is erased when the BeginPaint function is called; if 
bFrase is zero, the background remains unchanged. If bErase is nonzero 
for any part of the update region, the background in the entire region is 
erased, not just in the given part. 


Parameter Type/Description 

hWnd HWND Identifies the window whose update region is 
to be modified. 

hgn HRGN _sIdentifies the region to be added to the 
update region. The region is assumed to have client 
coordinates. 

bErase BOOL Specifies whether the background within the 


update region is to be erased. 


Return Value 


None 


Comments 


Windows sends a WM_ PAINT message to a window whenever its update 
region is not empty and there are no other messages in the application 
queue for that window. 


The given region must have been previously created by using one of the 


region functions (for more information, see Chapter 2, “Functions Over- 
view” ). 
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void InvertRect(hDC, lpRect) 


This function inverts the contents of the given rectangle. On monochrome 
displays, the InvertRect function makes white pixels black, and black 
pixels white. On color displays, the inversion depends on how colors are 
generated for the display. Calling InvertRect twice wie the same rectan- 
gle restores the display to its previous colors. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

loRect LPRECT Points toa RECT data structure that 
contains the logical coordinates of the rectangle to be 
inverted. 


Return Value 
None 


Comments 


The InvertRect function compares the values of the top, bottom, left, 
and right fields of the specified rectangle. If bottom 1s less than or equal 
to top, or if right is less than or equal to left, the rectangle is not drawn. 


BOOL InvertRgn(hDC, hRgn) 


This function inverts the colors in the region specified by the hRgn param- 
eter. On monochrome displays, the InvertRgn function makes white pix- 
els black, and black pixels white. On color displays, the inversion depends 
on how the colors are generated for the display. 


Parameter Type/Description 
hDC HDC Identifies the device context for the region. 
hRgn HRGN _ Identifies the region to be filled. The region 


is assumed to have logical coordinates. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
function is successful. Otherwise, it is zero. 
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BOOL IsChild(hWndParent, hWnd) 


This function indicates whether the window specified by the hWnd param- 
eter is a child window or other direct descendant of the window specified 
by the hWndParent parameter. A child window is the direct descendant of 
a given parent window if that parent window is in the chain of parent win- 
dows that leads from the original pop-up window to the child window. 


Parameter Type/Description 
hWndParent HWND Identifies a window. 

hWnd HWND Identifies the window to be checked. 
Return Value 

The return value specifies the outcome of the function. It is TRUE if the 


window identified by the hWnd parameter is a child window of the window 
identified by the hWndParent parameter. Otherwise, it 1s FALSE. 


BOOL IsClipboardFormatAvailable(wFormat) 


This function specifies whether data of a certain type exist in the 
clipboard. 


Parameter Type/Description 


wFormat WORD Specifies a registered format. 


Return Value 


The return value specifies the outcome of the function. It is TRUE if data 
having the specified format are present. Otherwise, it is FALSE. 


Comments 


This function is typically called during processing of the WM_INITMENU 
or WM_INITMENUPOPUP message to determine whether the clipboard 
contains data that the application can paste. If such data are present, the 
application typically enables the Paste command (in its Edit menu). 
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BOOL IsDialogMessage(hDlg, [pMsq) 


This function determines whether the given message is intended for the 
modeless dialog box specified by the hDlg parameter, and automatically 
processes the message if it is. When the IsDialogMessage function 
processes a message, 1t checks for keyboard messages and converts them 
into selection commands for the corresponding dialog box. For example, 
the TAB key selects the next control or group of controls, and the DOWN 
key selects the next control in a group. 


If a message is processed by IsDialogMessage, it must not be passed to 
the TranslateMessage or DispatchMessage function. This is because 
IsDialogMessage performs all necessary translating and dispatching of 
messages. 


IsDialogMessage sends WM_ GETDLGCODE messages to the dialog 
function to determine which keys should be processed. 


Parameter Type/Description 
hDlg HWND Identifies the dialog box. 
lpMsg LPMSG Points to an MSG data structure that 


contains the message to be checked. 


Return Value 


The return value specifies whether or not the given message has been 
processed. It is nonzero if the message has been processed. Otherwise, it 
is Zero. 


Comments 


Although IsDialogMessage is intended for modeless dialog boxes, it can 
be used with any window that contains controls to provide the same key- 
board selection as in a dialog box. 


WORD IsDigButtonChecked(hDig, nIDButton) 


This function determines whether a button control has a checkmark next 
to it, and whether a three-state button control is grayed, checked, or 
neither. The IsDlgButtonChecked function sends 2a BM- GETCHECK 


message to the button control. 
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Parameter Type/Description 


hDig HWND Identifies the dialog box that contains the 
button control. 

nIDButton int Specifies the integer identifier of the button 
control. 


Return Value 
The return value specifies the outcome of the function. It is nonzero if the 
given control has a checkmark next to it. Otherwise, it is zero. For three- 


state buttons, the return value is 2 if the button is grayed, 1 if the button 
has a checkmark next to it, and zero otherwise. 


BOOL IslIconic(hWnd) 


This function specifies whether a window is open or closed (iconic). 
Parameter Type/Description 
hWnd HWND Identifies the window. 


Return Value 


The return value specifies whether the window is open or closed (iconic). 
It is nonzero if the window is closed. It is zero if the window is open. 


BOOL IsRectEmpty(/pRect) 


This function determines whether or not the specified rectangle is empty. 
A rectangle is empty if the width and/or height are zero. 


Parameter Type/Description 


lpRect LPRECT Points toa RECT data structure that 
contains the specified rectangle. 


Return Value 


The return value specifies whether or not the given rectangle is empty. It 
is nonzero if the rectangle is empty. It is zero if the rectangle is not empty. 
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BOOL IsWindow(hWnd) 


This function determines whether the window identified by the hWnd 
parameter is a valid, existing window. 


Parameter Type/Description 
hWnd HWND Identifies the window. 


Return Value 


The return value specifies whether or not the given window is valid. It is 
nonzero if hWnd is a valid window. Otherwise, it is zero. 


BOOL IsWindowEnabled(hWnd) 


This function specifies whether the specified window is enabled for mouse 
and keyboard input. 


Parameter Type/ Description 
hWnd HWND _Identifies the window. 
Return Value 


The return value specifies whether or not the given window is enabled. It is 
nonzero if the window is enabled. Otherwise, it is zero. 


Comments 


A child window receives input only if it is both enabled and visible. 


BOOL IsWindowVisible(h Wnd) 
The IsWindowVisible function returns nonzero anytime an application 
has made a window visible by using the Show Window function (even 


if the specified window is completely covered by another child or pop-up 
window, the return value is nonzero). 


Parameter Type/Description 


hWnd HWND Identifies the window. 
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Return Value 
The return value specifies whether or not a given window exists on the 


screen. It is nonzero if the given window exists on the screen. Otherwise, it 
is zero, 


BOOL IsZoomed(h Wnd) 


This function determines whether or not a window has been maximized. 


Parameter Type/Description 
hWnd HWND Identifies the window. 
Return Value 


The return value specifies whether or not the given window is maximized. 
It is nonzero if the window is maximized. If the window is normal or 
iconic, the return value is zero. 
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BOOL KillTimer(hWnd, nIDEvent) 


This function kills the timer event identified by the hWnd and nlDEvent 
parameters. Any pending WM_ TIMER messages associated with the timer 
are removed from the message queue. 


Parameter Type/Description 

hWnd HWND Identifies the window associated with the 
given timer event. 

nlDEvent short Specifies the timer event to be killed. This 


must be a valid event identifier returned by the 
Set Timer function. 


Return Value 
The return value specifies the outcome of the function. It is nonzero if 


the event is killed. It is zero if the KillTimer function cannot find the 
specified timer event. 


349 


LineDDA 


void LineDDA(X1, Y1, X2, Y2, lpLineFunc, lpData) 


This function computes all successive points in a line starting at the point 
specified by the Xi and Yi parameters and ending at the point specified 
by the X2and Y2 parameters. The endpoint is not included as part of 
the line. For each point on the line, the LineDDA function calls the 
application-supplied function pointed to by the /pLineFunc parameter, 
passing to the function the coordinates of the current point and the 
lpData parameter. 


Parameter Type/Description 

X1 short Specifies the logical a-coordinate of the first 
point. 

Yi short Specifies the logical ycoordinate of the first 
point. 

X2 short Specifies the logical 2-coordinate of the end- 
point. 

Y2 short Specifies the logical ycoordinate of the end- 
point. 

lpLineFunc FARPROC Is the procedure-instance address of 


the application-supplied function. See the following 
“Comments” section for details. 


lpData LPSTR Points to the application-supplied data. 
Return Value 


None 


Comments 


The address passed by the IpLineF'unc parameter must be created by using 
the MakeProcInstance function. 


The callback function must use the Pascal calling convention and must be 
declared FAR. The callback function must have the following form: 


void FAR PASCAL LineFunc(X, Y, lpData) 
short X3 

short Y; 

LPSTR /pData; 


LineF unc is a placeholder for the application-supplied function name. The 


actual name must be exported by including it in an EXPORTS state- 
ment in the application’s module-definition file. 
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Parameter Definition 

X Specifies the z-coordinate of the current point. 
Y Specifies the ycoordinate of the current point. 
lpData Points to the application-supplied data. 


Return Value 


The function can perform any task. It has no return value. 


BOOL LineTo(hDC, X, Y) 


This function draws a line from the current position up to, but not includ- 
ing, the point specified by the X and Y parameters. The line is drawn with 
the selected pen. If no error occurs, the position is set to (X, Y) 


Parameter Type/Description 
hDC HDC | Identifies the device context. 
xX short Specifies the logical zcoordinate of the end- 


point for the line. 


Y short Specifies the logical ycoordinate of the end- 
point for the line. 


Return Value 


The return value specifies whether or not the line is drawn. It is nonzero if 
the line is drawn. Otherwise, it is zero. 


HANDLE LoadAccelerators(hInstance, lp TableName) 

This function loads the accelerator table named by the lp TableName 
parameter from the executable file associated with the module specified 
by the hAlnstance parameter. 


The LoadAccelerators function loads the table only if it has not been 
previously loaded. Otherwise, it retrieves a handle to the loaded table. 
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Parameter Type/Description 


hInstance HANDLE Identifies an instance of the module whose 
executable file contains the accelerator table. 


lp TableName LPSTR. Points to astring that names the accelerator 
table. The string must be a null-terminated character 
string. 


Return Value 


The return value identifies the loaded accelerator table if the function is 
successful. Otherwise, it is NULL. 


HBITMAP LoadBitmap(hInstance, lpBitmapName) 


This function loads the bitmap resource named by the lpBitmapName 
parameter from the executable file associated with the module specified 
by the hInstance parameter. The LoadBitmap function loads the 
resource into memory only if it has not been previously loaded. Other- 
wise, it retrieves a handle to the existing resource. 


Parameter Type/Description 
hInstance HANDLE Identifies the instance of the module 
whose executable file contains the bitmap. 


lypBitmapName LPSTR Points toa character string that names the 
bitmap. The string must be a null-terminated character 
string. 


Return Value 


The return value identifies the specified bitmap. It is NULL if no such bit- 
map exists. 


Comments 


The LoadBitmap function assumes that the bitmap is stored in a device- 
independent format. The function stretches or compresses the bitmap to 
accommodate the system’s aspect ratio and resolution. 


The lpBitmapName parameter can also be a value created by the 


MakelIntResource function. If it is, the ID must reside in the low-order 
word of lpBitmapName, and the high-order word must contain zeros. 
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HCURSOR LoadCursor(hlnstance, IpCursorName) 


This function loads the cursor resource named by the IlpCursorName 
parameter from the executable file associated with the module specified by 
the hInstance parameter. The function loads the cursor into memory only 
if it has not been previously loaded. Otherwise, it retrieves a handle to the 
existing resource. 


Parameter Type/Description 
hInstance HANDLE Identifies an instance of the module whose 
executable file contains the cursor. 


loCursorName LPSTR Points to a character string that names the 
cursor resource. The string must be a null-terminated 
character string. 


Return Value 


The return value identifies the newly loaded cursor if the function is suc- 
cessful. Otherwise, it is NULL. 


Comments 


The LoadCursor function can also be used to access the predefined cur- 
sors used by Windows. The hlnstance parameter must be set to NULL, and 
the IpCursorName parameter must be one of the following values: 


IDC_ ARROW Standard arrow cursor 
IDC. CROSS Crosshair cursor 
IDC_IBEAM Text I-beam cursor 
IDC_ ICON Empty icon 

IDC_ SIZE Four-pointed arrow 
IDC_ UPARROW Vertical arrow cursor 
IDC. WAIT Hourglass cursor 


The lpCursorName parameter can also be a value created by the 
MakelIntResource function. If it is, the ID must reside in the low- 
order word of [pCursorName, and the high-order word must contain 
Zeros. 
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HICON LoadiIcon(hInstance, IpIconName) 


This function loads the icon resource named by the IplconName param- 
eter from the executable file associated with the module specified by the 
hInstance parameter. The function loads the icon only if it has not been 
previously loaded. Otherwise, it retrieves a handle to the loaded resource. 


Parameter Type/Description 

hInstance HANDLE Identifies an instance of the module whose 
executable file contains the icon. 

lplconName LPSTR Points to a character string that names the 


icon resource. The string must be a null-terminated 
character string. 


Return Value 


The return value identifies an icon resource if the function is successful. 
Otherwise, it is NULL. 


Comments 
The LoadIcon function can also be used to access the predefined icons 


used by Windows. The hlnstance parameter must be set to NULL, and the 
lpIconName parameter must be one of the following values: 


IDI_ APPLICATION Default application icon 


IDI_ ASTERISK Asterisk (used in informative messages) 

IDI_EXCLAMATION _ Exclamation point (used in warning 
messages) 

IDI_ HAND Hand-shaped icon (used in serious warning 
messages) 

IDI. QUESTION Question mark (used in prompting messages) 


The [pIconName parameter can also be a value created by the 
MakelIntResource function. If it is, the [D must reside in the low- 
order word of lplconName, and the high-order word must contain 
ZeTOS. | 
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HANDLE LoadLibrary (lpLibFileName) 


This function loads the library module contained in the specified file and 
retrieves a handle to the loaded module. 


Parameter Type/ Description 


lpLibFileName LPSTR Points to a string that names the library file. 
The string must be a null-terminated character string. 


Return Value 


The return value identifies the loaded library module. It is NULL if the 
given file is not a library file. If the return value is less than 32, the value 
represents a DOS system-call error code (2, 8, or 11). 


HMENU LoadMenu(hInstance, lpMenuName) 


This function loads the menu resource named by the IpMenuName param- 
eter from the executable file associated with the module specified by the 
hInstance parameter. 


The function loads the menu only if it has not been previously loaded. 
Otherwise, it retrieves a handle to the loaded resource. 


Parameter Type/Description 
hInstance HANDLE | Identifies an instance of the module whose 
executable file contains the menu. 


lpMenuName LPSTR Points to a character string that names the 
menu resource. The string must be a null-terminated 
character string. 


Return Value 


The return value identifies a menu resource if the function is successful. 


Otherwise, it is NULL. 


Comments 


The lpMenuName parameter can also be a value created by the 
MakelIntResource function. If it is, the ID must reside in the low- 
order word of lpMenuName, and the high-order word must contain 
Zeros. 
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HMENU LoadMenulndirect(lpMenuTemplate) 


This function loads the menu resource named by the lpMenuTemplate 
parameter. The template specified by lpMenu Template is a collection of 
one or more MENUITEMTEMPLATE structures, each of which may 


contain one or more menu items and pop-up menus. 


The function loads the menu only if it has not been previously loaded. 
Otherwise, it retrieves a handle to the loaded resource. 


Parameter Type/Description 


lpMenuTemplate LPSTR Points to a menu template (which is a 
collection of one or more MENUITEMTEMPLATE 


structures). 


Return Value 


The return value identifies a menu resource if the function is successful. 
Otherwise, it is NULL. 


HANDLE LoadResource(hInstance, hResInfo) 


This function loads a resource identified by the hResInfo parameter from 
the executable file associated with the module specified by the Alnstance 
parameter. The function loads the resource into memory only if it has not 
been previously loaded. Otherwise, it retrieves a handle to the existing 
resource. 


Parameter Type/Description 

hInstance HANDLE Identifies an instance of the module 
whose executable file contains the resource. 

hResInfo HANDLE Identifies the desired resource. This 


handle is assumed to have been created by using the 
FindResource function. 


Return Value 


The return value identifies the global memory block to receive the data 
associated with the resource. It is NULL if no such resource exists. 
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Comments 


The resource is not actually loaded until the LockResource function 
is called to translate the handle returned by LoadResource into a far 
pointer to the resource data. 


int LoadString(hInstance, wlD, lpBuffer, nBufferMaz) 


This function loads a string resource identified by the w/D parameter from 
the executable file associated with the module specified by the hInstance 
parameter. The function copies the string into the buffer pointed to by the 
lpBuffer parameter, and appends a terminating null character. 


Parameter Type/Description 


hInstance HANDLE _ Identifies an instance of the module whose 
executable file contains the string resource. 


wlD unsigned Specifies the integer identifier of the string 
to be loaded. 

lpBuffer LPSTR Points to the buffer that receives the string. 

nBufferMax int Specifies the maximum number of characters to 


be copied to the buffer. The string is truncated if it is 
longer than the number of characters specified. 


Return Value 


The return value specifies the actual number of characters copied into the 
buffer. It is zero if the string resource does not exist. 


BYTE LOBYTE(nJnieger) 


This macro extracts the low-order byte from the short-integer value 
specified by the nlnteger parameter. 


Parameter Type/Description 


nInteger int Specifies the value to be converted. 


Return Value 


The return value specifies the low-order byte of the value. 
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HANDLE LocalAlloc(wFlags, wBytes) 


This function allocates the number of bytes of memory specified by the 
wBytes parameter from the local heap. The memory block can be either 
fixed or movable, as specified by the wFlags parameter. 


Parameter Type/Description 

wk lags WORD _ Specifies how to allocate memory. It can be 
one or more of the following values: 
Value Meaning 
LMEM_ DISCARDABLE 


Allocates discardable memory. 
May only be used with 


LMEMW. MOVEABLE. 
LMEM_ MODIFY Modifies the 

LMEM.. DISCARDABLE flag. 

May only be used with 

LMEM_ DISCARDABLE. 
LMEM_ FIXED Allocates fixed memory. 
LMEM_ MOVEABLE 


Allocates movable memory. Can- 


not be used with LMEM_ FIXED. 
LMEMW NOCOMPACT | 


Does not compact or discard 
memory to satisfy the allocation 
request. 


LMEM_ NODISCARD 
Does not discard memory to 
satisfy the allocation request. 


LMEM. ZEROINIT [Initializes memory contents to 


Zero. 


Choose LMEM_FIXED or LMEM- MOVEABLE, and 
then combine others as needed by using the bitwise OR 
operator. 


wBytes WORD Specifies the total number of bytes to be 
allocated. 
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Return Value 


The return value identifies the newly allocated local memory block if the 
function is successful. Otherwise, it is NULL. 


WORD LocalCompact(wMinF ree) 


This function generates the number of free bytes of memory specified by 
the wMinF'ree parameter by compacting, if necessary, the module’s local 
heap. The function checks the local heap for the specified number of con- 
tiguous free bytes. If the bytes do not exist, the LocalCompact function 
compacts local memory by first moving all unlocked movable blocks into 
high memory. If this does not generate the requested amount of space, the 
function discards discardable, movable blocks that are not locked down, 
until the requested amount of space is generated. 


Parameter Type/Description 
wMinF ree WORD _ Specifies the number of free bytes desired. 


If wMinF ree is zero, the function returns a value but 
does not compact memory. 


Return Value 


The return value specifies the number of bytes in the largest block of free 
local memory. 


HANDLE LocalDiscard(hMem) 


This function discards the local memory block specified by the hMem 
parameter. 


Parameter Type/Description 
hMem HANDLE _ Identifies the local memory block to be 
discarded. 


Return Value 


The return value specifies the outcome of the function. It is NULL if the 
function is successful. Otherwise, it is equal to hMem. 
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WORD LocalFlags(hMem) 


This function returns information about the specified local memory block. 


Parameter Type/ Description 


hMem HANDLE Identifies the local memory block. 


Return Value 


The return value contains one of the following memory-allocation flags in 
the high byte: 


LMEM_ DISCARDABLE _ Block is marked as discardable. 
LMEM_ DISCARDED Block has been discarded. 
The low byte of the return value contains the reference count of the block. 


Use the LMEM_ LOCKCOUNT mask to retrieve the lock-count value from 
the return value. 


HANDLE LocalFree(hMem) 


This function frees the local memory block identified by the hMem 
parameter. 


Parameter Type/Description 


hMem HANDLE Identifies the local memory block to 
be freed. 


Return Value 


The return value specifies the outcome of the function. It is NULL if the 
function is successful. Otherwise, it is equal to hMem. 
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void LocalFreeze(Dummy) 


This macro prevents the local heap from being compacted. The 
LocalMelt function can subsequently be called to allow compacting. 


Parameter Type/Description 
Dummy int Is not used; can be set to zero. 


Return Value 


None 


HANDLE LocalHandle(wMem) 


This function retrieves the handle of the local memory object whose 
address is specified by the wMem parameter. 


Parameter Type/Description 
wMem WORD Specifies the address of a local memory 
object. 


Return Value 


_ The return value identifies the local memory object. 


short LocalHandleDelta(nNewDelia) 
This function sets the number of handle-table entries to be allocated when 


the local heap manager runs out of handle-table entries for local movable 
objects. 


Parameter Type/Description 


nNewDelta int Specifies the number of handle-table entries to be 
allocated (the handle delta). 


Return Value 


The return value specifies the current handle delta. If nNewDelta is zero, 
the current handle delta is returned. 
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BOOL Locallnit(wSegment, wStart, wknd) 


This function initializes a local heap in the segment specified by the 
wSegment parameter. 


Parameter Type/ Description 

wSegment WORD Specifies the segment address of the segment 
that is to contain the local heap. 

wotart WORD Specifies the address of the start of the local 
heap within the segment. 

wlind WORD Specifies the address of the end of the local 


heap within the segment. 


Return Value 


The return value specifies a Boolean value that is nonzero if the heap is 
initialized. Otherwise, it 1s zero. 


Comments 


If the wStart parameter is zero, the default starting position for the local 
heap is the number of bytes specified by the wind parameter from the end 
of the given segment. 


char NEAR * LocalLock(hMem) 


This function locks the local memory block specified by the hMem param- 
eter. The block is locked into memory at the given address and its refer- 
ence count is increased by one. Locked memory cannot be moved or 
discarded. The block remains locked in memory until its reference count 
is decreased to zero by using the LocalUnlock function. 


Parameter Type/Description 


hMem ee Identifies the local memory block to be 
ocked. 


Return Value 


The return value points to the first byte of memory in the local block if 
the function is successful. Otherwise, it is NULL. 
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void LocalMelt(Dummy) 


This macro allows compacting of the local heap. It can be used after the 
LocalF reeze function has been called. 


Parameter Type/Description 
Dummy int Is not used; can be set to zero. 


Return Value 


None 


FARPROC LocalNotify (lpNotifyFunc) 
This function sets the address of the local-heap notification handler. The 
local-heap notification handler processes notification messages generated 


by Windows when certain actions occur, such as a request to increase the 
size of the heap. 


Parameter Type/Description 


lpNotifyFunc FARPROC Is the procedure-instance address of the 
local-heap notification handler. 


Return Value 


The return value points to the previous notification-message handler. 


Comments 


The address passed as the IpNotifyFunc parameter must be created by 
using the MakeProcInstance function. 


The callback function must use the Pascal calling convention and must 
be declared FAR. The callback function must have the following form: 


BOOL FAR PASCAL NotifyFunc(wMsg, hMem, wArg) 
WORD wMszq; 

HANDLE hMem; 

WORD waArg; 
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NotifyFunc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Definition 
wMsg Specifies the notification message. 
hMem Identifies the local memory object that generated 


the notification. 


wArg Specifies the argument determined by the value 
of the wMsg parameter. 


Return Value 


The return value is nonzero if the function is successful. 


HANDLE LocalReAlloc(hMem, wBytes, wk lags) 


This function reallocates the local memory block specified by the hMem 
parameter by increasing or decreasing its size to the number of bytes 
specified by the wBytes parameter. 


Parameter Type/ Description 

hMem HANDLE Identifies the local memory block to be 
reallocated. 

wBytes WORD Specifies the new size of the memory block. 

wk lags WORD Specifies how to reallocate the local memory 
block. It can be one or more of the following values: 
Value Meaning 
LMEM_ DISCARDABLE 


Memory is discardable. This 
flag can only be used with 


LMEM_ MODIFY. 
LMEM_ MODIFY Memory flags are modified. The 


wBytes parameter 1s ignored. 
This flag can only be used with 
LMEM_ DISCARDABLE. 
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LocalReAlloc 


LMEM_ MOVEABLE 
Memory is movable. If wBytes is 
zero, this flag causes a previously 
fixed block to be freed or a previ- 
ously movable object to be dis- 
carded {if the block’s reference 
count is zero). If wBytes is nonzero 
and the block specified by hMem is 
fixed, this flag allows the reallo- 
cated block to be moved to a new 
fixed location. (Note that the han- 
dle returned by the LocalReAlloc 
function in this case may be dif- 
ferent from the handle passed to the 
function.) Use only if memory flags 
cannot be modified. 


LMEM_~ NOCOMPACT | 
Memory will not be compacted or 
discarded to satisfy the allocation 
request. Use only if memory flags 
cannot be modified. 


LMEM_ NODISCARD 
Objects will not be discarded to 
satisfy the allocation request. Use 
only if memory flags cannot be 
modified. 


LMEM_ ZEROINIT 
If the block is growing, the addi- 
tional memory contents are initial- 
ized to zero. Use only if memory 
flags cannot be modified. 


The return value identifies the reallocated local memory if the function is 
successful. It is NULL if the local memory block cannot be reallocated. 


The return value is always identical to the hMem parameter, unless the 
LMEM_ MOVEABLE flag is used to allow movement of a fixed block of 
memory to a new fixed location. 
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WORD LocalShrink(hSeg, wSize) 


This function shrinks the specified heap to the size specified by the wSize 
parameter. The minimum size for the automatic local heap is defined in 
the application’s module-definition file. 


Parameter Type/Description 

hSeg HANDLE Identifies the segment that contains the 
local heap. 

wSize WORD Specifies the size (in bytes) desired for the 


local heap after shrinkage. 


Return Value 


The return value specifies the size of the local heap after shrinkage. 


Comments 

If hSeg is zero, the LocalShrink function reduces the local heap in the 
current data segment. Windows will not shrink that portion of the data 
segment that contains the stack and the static variables. 


Use the GlobalSize function to determine the new size of the data 
segment. 


WORD LocalSize(hMem) 


This function retrieves the current size (in bytes) of the local memory 
block specified by the hMem parameter. 


Parameter Type/Description 


hMem HANDLE Identifies the local memory block. 


Return Value 


The return value specifies the size (in bytes) of the specified memory block. 
It is NULL if the given handle is ‘not valid. 
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Comments 


The actual size of a memory block sometimes is larger than the size 
requested when the memory was allocated. 


BOOL LocalUnlock(hMem) 


This function unlocks the local memory block specified by the hMem 
parameter and decreases the block’s reference count by one. The block is 
completely unlocked, and subject to moving or discarding, if the reference 
count is decreased to zero. 


Parameter Type/Description 

hMem HANDLE Identifies the local memory block to be 
unlocked. 

Return Value 


The return value specifies the locked state of the local memory block. It is 
nonzero if the block was previously locked. It is zero if the block was not 
previously locked. 


HANDLE LockData(Dummy) 


This macro locks the current data segment in memory. It is intended to be 
used in modules that have movable data segments. 


Parameter Type/Description 
Dummy int Is not used; can be set to zero. 


Return Value 


The return value identifies the locked data segment if the function is 
successful. Otherwise, it is NULL. 
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LPSTR LockResource(hResData) 


This function retrieves the absolute memory address of the loaded resource 
identified by the hResData parameter. The resource is locked in memory 
and the given address and its reference count are increased by one. The 
locked resource is not subject to moving or discarding. 


The resource remains locked in memory until its reference count is 
decreased to zero through calls to the FreeResource function. 


If the resource identified by hResData has been discarded, the resource- 
handler function (if any) associated with the resource is called before the 
LockResource function returns. The resource-handler function can recal- 
culate and reload the resource if desired. After the resource-handler func- 
tion returns, LockResource makes another attempt to lock the resource 
and returns with the result. 


Parameter Type/Description 
hResData HANDLE Identifies the desired resource. This 


handle is assumed to have been created by using 
the LoadResource function. 


Return Value 


The return value points to the first byte of the loaded resource if the 
resource was locked. Otherwise, it is NULL. 


Comments 


Using the handle returned by the FindResource function for the 
hResData parameter causes an error. 


Use the UnlockResource function to unlock a resource that was locked 
by using LockResource. 


HANDLE LockSegment(wSegment) 
This function locks the segment whose segment address is specified by the 


wSegment parameter. If wSegment is —1, the LockSegment function locks 
the current data segment. 
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Parameter Type/Description 


wSegment WORD | Specifies the segment address of the 
segment to be locked. 


Return Value 


The return value identifies the locked segment. 


WORD LOWORD(lInteger) 


This macro extracts the low-order word from the long value specified by 
the (/nteger parameter. 


Parameter Type/Description 


lInteger long Specifies the value to be converted. 


Return Value 


The return value specifies the low-order word of the long value. 


BOOL LPtoDP(hDC, lpPoints, nCount) 


This function converts logical points into device points. The LPtoDP 
function maps the coordinates of each point specified by the lpPoints 
parameter from GDI’s logical coordinate system into a device coordinate 
system. The conversion depends on the current mapping mode. 


Parameter Type/Description 
hDC HANDLE Identifies the device context. 
lpPoints LPPOINT Points to an array of points. Each point 


in the array is a POINT data structure. 


nCount short Specifies the number of points in the array. 


Return Value 


The return value specifies whether or not all points are converted. It is 
nonzero if all points are converted. Otherwise, it is zero. 
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LPSTR MAKEINTATOM(wlnteger) 


This macro creates an integer atom that represents a character string of 
decimal digits. 


Integer atoms created by this macro can be added to the atom table by 
means of the AddAtom function. 


Parameter Type/Description 


winteger WORD Specifies the numeric value of the atom’s 
character string. 3 


Return Value 
The return value points to the atom created for the given integer. 


Comments 
The DeleteAtom function always succeeds for integer atoms, even though 


it does nothing, and the GetAtomName function always returns the 
string form of the integer atom (for example, #123). 


LPSTR MAKEINTRESOURCE (nInteger) 


This macro converts an integer value into a long pointer to a string, with 
the high-order word of the long pointer set to zero. 


Parameter Type/Description 


ninteger int Specifies the integer value to be converted. 


Return Value 


The return value points to a string. 


DWORD MAKELONG(nLowWord,nHigh Word) 


This macro creates an unsigned long integer by concatenating two integer 
values, specified by the nLowWord and nHighWord parameters. 
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Parameter Type/ Description 

nLowWord int Specifies the low-order word of the new long value. 

nHighWord int Specifies the high-order word of the new long 
value. 


Return Value 


The return value specifies an unsigned long-integer value. 


POINT MAKEPOINT(lInteger) 


This macro converts a long value that contains the a and ycoordinates of 
a point into a POINT data structure. 


Parameter Type/Description 


lInteger LONG Specifies the a- and y-coordinates of a point. 


Return Value 


The return value specifies the POINT data structure. 


FARPROC MakeProclInstance(lpProc, hInstance) 


This function creates a procedure-instance address. A procedure-instance 
address points to prologue code that is executed before the function is exe- 
cuted. The prologue binds the data segment of the instance specified by 
the hInstance parameter to the function pointed to by the lpProc parame- 
ter. Thus, when the function is executed, it has access to variables and 
data in that instance’s data segment. 


Parameter Type/ Description 
lyProc FARPROC Is a procedure-instance address. 
hInstance HANDLE Identifies the instance associated with the 


desired data segment. 


Return Value 


The return value points to the function if the function is successful. Other- 


wise, it is NULL. 
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Comments 


The MakeProclInstance function must only be used to access functions 
from instances of the current module. The function is not required if the 
module has a single data segment for all instances. The GetProcAddress 
function should be used to access functions exported by other modules. 


After MakeProcInstance has been called for a particular function, all 
calls to that function should be made through the retrieved address. 


MakeProclInstance can create no more than one procedure instance of 
an application. This means that after a procedure instance has been 
created, subsequent calls using the same function and instance return the 
same result. 


To bind a data segment to a function, the function must be exported in 
the EXPORTS statement of the module-definition file. 


void MapDialogRect(hDlg, lpRect) 


This function converts the dialog-box units given in the /pRect parameter 
to screen units. Dialog-box units are stated in terms of the width and 
height of characters in the system font. One horizontal unit is one-fourth 
of a character, and one vertical unit is one-eighth of a character. The 
MapDialogRect function replaces the dialog-box units in /pRect with 
screen units (pixels), so that the rectangle can be used to create a dialog 
box or position a control within a box. 


Parameter Type/Description 
hDlg | HWND Identifies a dialog box. 
loRect LPRECT Points toa RECT data structure that 


contains the dialog-box coordinates to be converted. 
Return Value 
None 
Comments 


The hDlg parameter must be created by using the CreateDialog or 
DialogBox function. 
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int max(value1, value?) 


This function returns the greater of the values contained in the valuei and 
value2 parameters. 


Parameter Type/Description 
valuel int Specifies the first of two values. 
value2 int Specifies the second of two values. 


Return Value 


The return value specifies value/ or value2, whichever is greater. 


BOOL MessageBeep(wType) 


This function generates a beep at the system speaker when a message box 
is displayed. 


Parameter Type/Description 


wType WORD Specifies an unsigned short-integer value 
that is the same as the wType parameter passed to the 
MessageBox function. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
function is successful. Otherwise, it is zero. 


int MessageBox(hWndParent, lpTeat, lpCaption, wT ype) 


This function creates and displays a window that contains an application- 
supphed message and caption, plus any combination of the predefined 
icons and push buttons described in the following list. 


Parameter Type/Description 


hWndParent HWND Identifies the window that owns the message 
box. The input focus is set to this window when the 
MessageBox function returns. 


lp Tezt LPSTR Points to the message to be displayed. The 
string must be a null-terminated character string. 
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lpCaption LPSTR Points to the character string to be used 
for the dialog-box caption. The string must be null- 
terminated. If the lpCaption parameter is NULL, the 
default caption “Error!” is used. 


wlype WORD Specifies the contents of the dialog box. 
It can be any combination of the values shown in 
Table 3.12, joined by the bitwise OR operator. 


Return Value 


The return value specifies the outcome of the function. It is zero if there 1s 
not enough memory to create the message box. Otherwise, it is one of the 
following menu-item values returned by the dialog box: 


IDABORT Abort button pressed. 
IDCANCEL Cancel button pressed. 
IDIGNORE Ignore button pressed. 
IDNO No button pressed. 
IDOK OK button pressed. 
IDRETRY Retry button pressed. 
IDYES Yes button pressed. 


If a message box has a Cancel button, the IDCANCEL value will be 
returned if either the Escape or Cancel button is pressed. If the message 
box has no Cancel button, pressing the Escape button has no effect. 


Comments 


When a system-modal message box is created to indicate that the system 
is low on memory, the strings passed as the lp Text and lpCaption parame- 
ters should not be taken from a resource file, since an attempt to load a 
resource file may fail. 


When an application calls the MessageBox function and specifies the 
MB. ICONHAND and MB_STEMMODAL flags for the wfype parameter, 
Windows will display the resulting message box regardless of available 
memory. When these flags are specified, Windows limits the length of the 
message-box text to one line. 


When the keyboard interface is used to enumerate windows, the message 
box and its parent window are considered to be next to each other. 
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If a message box is created while a dialog box is present, use the handle of 
the dialog box as the hWndParent parameter. 


Table 3.12 shows the contents of a dialog-box: 


Table 3.12 
Dialog-Box Contents 


Value 


MB_ ABORTRETRYIGNORE 


MB_ APPLMODAL 


MB_DEFBUTTONI 


MB... DEFBUTTON2 

MB. DEFBUTTONS 

MB_ ICONASTERISK 

MB_ ICONEXCLAMATION 


MB_ ICONHAND 
MB. ICONQUESTION 


MB_ OK 
MB. OKCANCEL 


MB_ RETRYCANCEL 


MB_SYSTEMMODAL 


MB_ YESNO 


MB_ YESNOCANCEL 


Meaning 


Message box contains three push buttons: 
Abort, Retry, and Ignore. 


The user must respond to the message box 
before continuing-work in the window 
identified by the hWndParent parameter. 
However, the user can move to the windows 
of other applications and work in those 


windows. — APPLMODAL is the default. 


First button is the default. Note that the 
first button is always the default unless 
MB_ DEF BUTTON2 or 

MB. DEFBUTTONS is specified. 


Second button is the default. 
Third button is the default. 
An asterisk icon appears in the message box. 


An exclamation-point icon appears in the 
message box. 


A hand icon appears in the message box. 


A question-mark icon appears in the 
message box. 


Message box contains one push button: OK. 


Message box contains two push buttons: OK 
and Cancel. 


Message box contains two push buttons: 
Retry and Cancel. 


All applications are suspended until the user 
responds to the message box. System-modal 
message boxes are used to notify the user of 
serious, potentially damaging errors that 
require immediate attention (for example, 
running out of memory). 


Message box contains two push buttons: Yes 
and No. 


Message box contains three push buttons: 
Yes, No, and Cancel. 
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int min(value1, value2) 


This macro returns the lesser of the values specified by the value/ and 
value2 parameters, respectively. 


Parameter Type/Description 
valuel int Specifies the first of two values. 
value? int Specifies the second of two values. 


Return Value 


The return value specifies valued or value2, whichever is less. 


DWORD MoveTo(hDC, X, Y) 


This function moves the current position to the point specified by the 
X and Y parameters. 


Parameter Type/Description | 

hDC HDC Identifies the device context. 

X short Specifies the logical zcoordinate of the new 
position. 

Y short Specifies the logical y-coordinate of the new 
position. 


Return Value 
The return value specifies the 2 and ycoordinates of the previous posi- 


tion. The y coordinate is in the high-order word; the acoordinate is in 
the low-order word. 


Comments 


Although the MoveTo function has no output, it affects other output 
functions that use the current position. 
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void MoveWindow(hWnd, X, Y, nWidih, nHeight, bRepaint) 


This function causes a WM_SIZE message to be sent to the given win- 
dow. The X, Y, nWidth, and nHeight parameters give the new size of the 
window. 


Parameter Type/Description 


hWnd HWND _ Identifies a pop-up or child window. 


X int Specifies the new 2-coordinate of the upper- 
left corner of the window. 


Y int Specifies the new y-coordinate of the upper- 
left corner of the window. For pop-up windows, 
Xand Y are in screen coordinates (relative to the 
upper-left corner of the screen}. For child windows, 
they are in client coordinates hehe to the upper- 
left corner of the parent window’s client area). 


nWidih int Specifies the new width of the window. 
nHeight int Specifies the new height of the window. 
bRepaint BOOL Specifies whether or not the window is 


repainted after moving. If bRepaznt is zero, the win- 
dow is not repainted. 


Return Value 


None 


Comments 


Any child or pop-up window has a minimum width and height. These 
minimums depend on the style and content of the window. Any attempt 
to make the width and height smaller than the minimum by using the 
Move Window function will fail. The WM_SIZE message created by this 
function gives the new width and height of the client area of the window, 
not of the full window. 
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BOOL Oem ToAnsi(lpOemStr, IpAnsiStr) 


This function translates the string pointed to by the lpOemStr parameter 
from the OEM-defined character set into the ANSI character set. 


Parameter Type/Description 

lp OemStr LPSTR Points to a null-terminated string of charac- 
ters from the OEM-defined character set. 

lnAnsiStr LPSTR Points to the location where the translated 


string is to be copied. The [pAnsiStr parameter can be 
the same as IpOemSér to translate the string in place. 


Return Value 


The return value specifies the outcome of the translation. It is nonzero if 
all characters in the OEM string have been translated into equivalent 
characters in the ANSI character set. It is zero if one or more characters in 
the OEM string has no direct equivalent in the ANSI character set. In such 
cases, an arbitrary ANSI character is selected for the translation. 


short OffsetClipRgn(hDC, X, Y) 


This function moves the clipping region of the given device by the specified 
offsets. The function moves the region X units along the z-axis and Y units 
along the y-axis. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

X short Specifies the number of logical units to move 
left or right. 

Y short Specifies the number of logical units to move 
up or down. 


378 


OffsetRect 


Return Value 


The return value specifies the new region’s type. It can be any one of the 
following values: 

COMPLEXREGION Clipping region has overlapping borders. 

ERROR Device context is not valid. 

NULLREGION Clipping region is empty. 

SIMPLEREGION Clipping region has no overlapping borders. 


void OffsetRect(lpRect, X, Y) 


This function moves the given rectangle by the specified offsets. The 
OffsetRect function moves the rectangle X units along the a-axis and 
Y units along the yaxis. The X and Y parameters are signed values, 
so the rectangle can be moved left or right, and up or down. 


Parameter Type/Description 


lnRect LPRECT Points toa RECT data structure that 
contains the rectangle to be moved. 


xX int Specifies the amount to move left or right. It must 
be negative to move left. 


Y int Specifies the amount to move up or down. It must 
be negative to move up. 


Return Value 

None 

Comments 

The coordinate values of a rectangle must not be greater than 32,767 or 


less than -32,768. The X and Y parameters must be chosen carefully to 
prevent invalid rectangles. | 
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short OffsetRgn(hRgn, X, Y) 


This function moves the given region by the specified offsets. The function 
moves the region X units along the waxis and Y units along the y-axis. 


Parameter Type/ Description 

hRgn HRGN Identifies the region to be moved. 

X short Specifies the number of units to move left or 
right. 

Y short Specifies the number of units to move up or 
down, 


Return Value 


The return value specifies the new region’s type. It can be any one of the 
following values: 


COMPLEXREGION Region has overlapping borders. 
ERROR Region handle is not valid. 
NULLREGION Region is empty. 

SIMPLEREGION Region has no overlapping borders. 


DWORD OffsetViewportOrg(hDC, X, Y) 


This function modifies the viewport origin relative to the current values. 
The formulas are written as follows: 


xNewVO = xOldVO +X 
yNewVO = yOldVO + Y 


The new origin is the sum of the current origin and the X and Y values. 


Parameter Type/ Description 
hDC HDC Identifies the device context. 
xX short Specifies the number of device units to add to 


the current origin’s 2-coordinate. 


Y short Specifies the number of device units to add to 
the current origin’s y coordinate. 
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Return Value 
The return value specifies the previous viewport origin (in device coordi- 


nates). The previous y-coordinate is in the high-order word; the previous 
z-coordinate is in the low-order word. 


DWORD OffsetWindowOrg(hDC, X, Y) 


This function modifies the viewport origin relative to the current values. 
The formulas are written as follows: 


xNewWO = xOldWO + X 
yNewWO = yOldWO + Y 


The new origin is the sum of the current origin and the X and Y values. 


Parameter Type/ Description 

hDC HDC Identifies the device context. 

X short Specifies the number of logical units to add to 
the current origin’s zcoordinate. 

Y short Specifies the number of logical units to add to 
the current origin’s y coordinate. = 


Return Value 
The return value specifies the previous window origin (in logical coordi- 


nates). The previous y-coordinate is in the high-order word; the previous 
g-coordinate is in the low-order word. 


BOOL OpenClipboard(hWnd) 


This function opens the clipboard for examination and prevents other 
applications from modifying the clipboard contents. 


Parameter Type/Description 


hWnd HWND Identifies the window to be associated with 
the open clipboard. 
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Return Value 


The return value specifies the status of the clipboard. It is nonzero if the 
clipboard is opened. If the clipboard has already been opened by another 
application, the return value is zero. 


short OpenComm(IpComName, nInQueue, nOut Queue) 


This function opens a communication device and assigns an nCid handle 
to it. The communication device is initialized to a default configuration. 
The SetCommState function should be used to initialize the device to 
alternate values. The OpenComm function allocates space for receive 
and transmit queues. The queues are used by the interrupt-driven 
transmit/receive software. 


Parameter Type/Description 


lnComName LPSTR Points to a string which contains COMn or 
LPTn, where n ranges from 1 to the number of commun- 
ication devices available for the particular type of I/O 


port. 
ninQueue int Specifies the size of the receive queue. 
nOutQueue int Specifies the size of the transmit queue. 


Return Value 


The return value specifies the open communication device. If an error 
occurs, the return value is one of the following negative error values: 


IE. BADID Invalid or unsupported ID. 
JE_ BAUDRATE Unsupported baud rate. 

IE_ BYTESIZE ~ Tnvalid byte size. 

IE. DEFAULT Error in default parameters. 
IE_ HARDWARE Hardware not present. 

TE_ MEMORY Unable to allocate queues. 
TE_ NOPEN Device not open. 

IE_ OPEN Device already open. 
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int OpenFile(lpFileName, IpReOpenBuff, wStyle) 
This function creates, opens, reopens, or deletes a file. 


Parameter Type/Description 


lpFileName LPSTR Points to a null-terminated character string 
that names the file to be opened. The string must con- 
sist of characters from the ANSI character set. 


lpReOpenBuf LPOFSTRUCT Points tothe OFSTRUCT data 
structure that 1s to receive information about the file 
when the file is first opened. The structure can be used 
in subsequent calls to the OpenFile function to refer to 
the open file. 


wdtyle WORD Specifies the action to take. These styles can 
be combined by using the bitwise OR operator: 


Value Meaning 


OF. CANCEL Adds a Cancel button to the 
OF_ PROMPT dialog box. Press- 
ing the Cancel button directs 
OpenF ile to return a file-not- 
found error message. 


OF_ CREATE Directs OpenFile to create a new 
file. If the file already exists, it is 
truncated to zero length. 


OF_DELETE __ Deletes the file. 
~ OF_ EXIST Opens the file, and then closes it. 
Used to test for file existence. 
OF_ PARSE Fills the OFSTRUCT data 
structure but carries out no other 
action. 
OF_ PROMPT Displays a dialog box that 


prompts the user for permission 
to create a file if the requested file 
does not exist. 


OF_ READ Opens the file for reading only. 

OF READWRITE = Opens the file for reading and 
writing. 

OF_ REOPEN Opens the file using information 


in the reopen buffer. 
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OF_ VERIFY Verifies that the date and time of 
the file are the same as when it 
was previously opened. Useful as 
an extra check for read-only files. 


OF. WRITE Opens the file for writing only. 


Return Value 


The return value specifies a DOS file handle if the function is successful. 
Otherwise, it 1s —1, 


Comments 
To close the file after use, use the DOS system close call. 
If wildcard characters are used in the filename, the OpenF ile function 


searches all directories in the PATH environment variable for a matching 
filename. 


BOOL Opentcon(h Wnd) 


This function opens the specified window by copying the window’s caption 
and client area to the screen and removing its icon from the icon area. 


If other open windows already exist on the screen, the OpenIcon func- 


tion directs Windows to resize those windows to make room for the new 
window. 


Parameter Type/ Description 
hWnd HWND _ Identifies the window. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
function is successful. Otherwise, it 1s zero. 


Comments 


This function has the same result as sending a WM_SYSCOMMAND mes- 


sage with its wParam parameter set to SC_ICON to an iconic window. 


Child and pop-up windows cannot be opened by using this function. 
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int OpenSound( ) 


This function accesses the play device and prevents it from being opened 
subsequently by other applications. 


This function has no parameters. 
Return Value 
The return value specifies the number of voices available. The return value 


is S.SERDVNA if the play device is in use, and S.SEROFM if insufficient 


memory is available. 
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BOOL PaintRgn(hDC, hRgn) 


This function fills the region specified by the hRgn parameter with the 
selected brush. 


Parameter Type/ Description 

hDC HDC Identifies the device context that contains the 
region. 

hRgn HRGN Identifies the region to be filled. The region is 


assumed to have logical coordinates. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
function is successful. Otherwise, it is zero. 


BOOL PatBlt(hDC, X, Y, nWidth, nHeight, dwRop) 


This function creates a bit pattern on the specified device. The pattern is a 
combination of the selected brush and the pattern already on the device. 
The raster-operation code specified by the dwRop parameter defines how 
the patterns are to be combined. 


Parameter Type/Description 


hDC HDC Identifies the device context. 

X short Specifies the logical coordinate of the upper- 
left corner of the rectangle that is to receive the pattern. 

Y short Specifies the logical ycoordinate of the upper- 
left corner of the rectangle that is to receive the pattern. 

nWidth short Specifies the width (in logical units) of the rect- 


angle that is to receive the pattern. 


nHeight short Specifies the height (in logical units) of the rect- 
angle that is to receive the pattern. 


dwRop Specifies the raster-operation code. Raster-operation 
codes (ROPs) define how GDI combines colors in output 
operations that involve a current brush, a possible 
source bitmap, and a destination bitmap. For a list of 
the raster-operation codes, see Table 3.13. 


PeekMessage 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
bit pattern is drawn. Otherwise, it is zero. 


Comments 


The values of dwRop for this function are a limited subset of the full 256 
ternary raster-operation codes; in particular, an operation code that refers 
to a source cannot be used. 


Not all devices support the PatBlt function. For more information, see 
the RC_ BITBLT capability in the GetDeviceCaps function, earlier in 
this chapter. 


Table 3.13 lists the raster-operation codes for the dwhop parameter: 


Table 3.13 


Raster Operations 
Code Description 


PATCOPY Copies pattern to destination bitmap. 


PATINVERT Combines destination bitmap with 
pattern using the Boolean OR operator. 


DSTINVERT Inverts the destination bitmap. 
BLACKNESS Turns all output black. 
WHITENESS ‘Turns all output white. 


BOOL PeekMessage(lpMsg, hWnd, wMsgFilterMin, wMsgFilter Maa, 
wRemoveMsg) 


This function checks the application queue for a message and places the 
message (if any) in the data structure pointed to by the lpMsg parameter. 
Unhke the GetMessage function, the PeekMessage function does not 
wait for a message to be placed in the queue before returning. It does, 
however, yield control (if the PM_NOYIELD flag isn’t set) and does 

not return control after the yield until Windows returns control to the 
application. 
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Peek Message retrieves only messages associated with the window spec- 
ified by the hWnd parameter and within the range of message values given 
by the wMsgFilterMin and wMsgFilterMaz parameters. If hWnd is NULL 
and wMsgFilterMin and wMsqFilterMaz are both zero, PeekMessage 
checks the entire queue for messages. 


The WM_KEYFIRST and WM_ KEYLAST flags can be used as filter 
values to retrieve all key messages; the WM_ MOUSEFIRST and 
WM_MOUSELAST flags can be used to retrieve all mouse messages. 


Parameter Type/Description 


loMsg LPMSG Points to an MSG data structure that 
contains message information from the Windows 
application queue. 


hWnd HWND Identifies the window whose messages are to 
be examined. 


wMsgFilterMin unsigned Specifies the value of the lowest message 
position to be examined. 


wMsgFilterMax WORD Specifies the value of the highest message 
. position to be examined. 


wRemoveMsg WORD Specifies a combination of the flags described 
in the following list. PM. NOYIELD can be combined 
with either PM. NOREMOVE or PM_ REMOVE: 


Value Meaning 


PM_NOREMOVE Messages are not removed from 
the queue after processing by 
PeekMessage. 


PMU. NOYIELD Prevents the current task from 
halting and yielding system 
resources to another task. _ 

PM. REMOVE Messages are removed from the 
queue after processing by Peek- 
Message. 


Return Value 


The return value specifies whether or not a message is found. It is nonzero 
if a message is available. Otherwise, it is zero. 
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Comments 


PeekMessage does not remove WM. PAINT messages from the queue. 
The messages remain in the queue until processed. The GetMessage, 
PeekMessage, and WaitMessage functions yield control to other appli- 
cations. These calls are the only way to let other applications run. If your 
application does not call any of these functions for long periods of time, 
other applications cannot run. 


When GetMessage, PeekMessage, and WaitMessage yield control to 
other applications, the stack and data segments of the application calling 
the function may move in memory to accommodate the changing memory 
requirements of other applications. 


If the application has stored long pointers to objects in the data or stack 
segment (that is, global or local variables}, these pointers can become 
invalid after a call to GetMessage, Peek Message, or WaitMessage. 
The lpMsg parameter of the called function remains valid in any case. 


BOOL Pie(hDC, X1, Y1, X28, Y2, X8, Y8, X4, Yd) 


This function draws a pie-shaped wedge by drawing an elliptical arc whose 
center and two endpoints are joined by lines. The center of the arc is the 
center of the bounding rectangle specified by the X1, Y1, X2, and Y2 
parameters. lhe starting and ending points of the arc are specified by the 
X8, Y3, X4, and Y4 parameters. The arc is drawn with the selected pen, 
moving in a counterclockwise direction. Two additional lines are drawn 
from each endpoint to the are’s center. The pie-shaped area is filled with 
the selected brush.. 


If X3 equals X4 and Y@ equals Y4, the result is an ellipse with a single line 
from the center of the ellipse to the points X38, Y8 (or X4, Y4). 


Parameter Type/Description 
ADC HDC Identifies the device context. 
X1 short Specifies the logical acoordinate of the upper- 


left corner of the bounding rectangle. 


Y1 | short Specifies the logical ycoordinate of the upper- 
left corner of the bounding rectangle. 


X2 short Specifies the logical #coordinate of the lower- 
right corner of the bounding rectangle. 


Y2 ' ghort Specifies the logical ycoordinate of the lower- 
7 right corner of the bounding rectangle. 
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X38 short Specifies the logical «coordinate of the starting 
point of the arc. This point does not have to lie exactly 
on the arc. 


Y3 short Specifies the logical ycoordinate of the starting 
point of the arc. This point does not have to lie exactly 
on the arc. 


X4 short Specifies the logical z-coordinate of the end- 
point of the arc. This point does not have to lie exactly 
on the arc. 


Y4 short Specifies the logical y coordinate of the end- 
point of the arc. This point does not have to lie exactly 
on the arc. 


Return Value 


The return value specifies whether or not the pie shape is drawn. It is 
nonzero if the pie shape is drawn. Otherwise, it 1s zero. 


Comments 

The width of the rectangle, specified by the absolute value of X2 — X1, 
must not exceed 32,767 units. This limit applies to the height of the 
rectangle as well. 


The current position is neither used nor updated by this function. 


BOOL PlayMetaFile(hDC, hMF) 


This function plays the contents of the specified metafile on the given 
device. The metafile can be played any number of times. 


Parameter Type/Description 

ADC HDC Identifies the device context associated with the 
metafile. 

hMF HANDLE Identifies the metafile. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
function is successful. Otherwise, it is zero. 
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void PlayMetaFileRecord(hDC, [pHandletable, lpMetaRecord, nHndl) 


This function plays a metafile record by executing the GDI function calls 
contained within the metafile record. A metafile record 1s a collection of 


GDI calls. 


Parameter Type/Description 


ADC HDC Identifies the device context associated with the 
metafile. 


lpHandletable LPSTR Points toa HANDLETABLE structure. 
lpMetaRecord LPSTR Points to the record that contains the 


metafile. 

nHndl WORD _ Specifies the number of handles in the handle 
table. 

Return Value 

None 

Comments 


An application typically uses this function in conjunction with the 
Enum Metafile function to modify and then play a metafile. 


BOOL Polygon(hDC, IpPoints, nCount) 


This function draws a polygon consisting of two or more points (vertices) 
connected by lines. The lines are drawn according to the current polygon- 
filling mode. In ALTERNATE mode, lines are drawn from the first point 
through subsequent points using the current pen, and the interior is filled 
with the current brush. In WINDING mode, all points are used to compute 
a border; the border is then drawn using the current pen, and the interior 
is filled with the current brush. For a description of how WINDING mode 
borders are computed, see the SetPolyFillMode function, later in this 
chapter. In both modes, the polygon is automatically closed, if necessary, 
by drawing a line from the last vertex to the first. 
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Parameter Type/Description 

hDC HDC Identifies the device context. 

lpPoints LPPOINT Points to an array of points that specify 
the vertices of the polygon. Each point in the array is a 
POINT data structure. 

nCount short Specifies the number of vertices given in the 
array. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
function is successful. Otherwise, it 1s zero. 


Comments 
The current position is neither used nor updated by this function. 


The current polygon-filling mode can be retrieved or set by using the 
GetPolyFillMode and SetPolyFillMode functions. 


BOOL Polyline(hDC, lpPoints, nCount) 


This function draws a set of line segments, connecting the points speci- 
fied by the /pPoints parameter. The lines are drawn from the first point 
through subsequent points with the result as if the MoveTo and LineTo 
functions were used to move to each new point and then connect it to the 
next. However, the current position is neither used nor updated by the 
Polyline function. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

lnPoints LPPOINT Points to an array of points to be con- 
nected. Each point in the array is a POINT data 
structure. 

nCount short Specifies the number of points in the array. 


The nCount parameter must be at least 2. 
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Return Value 


The return value specifies whether or not the line segments are drawn. It is 
nonzero if the line segments are drawn. Otherwise, it is zero. 


Comments 


This function draws lines with the selected pen. 


BOOL PostAppMessage(h Task, wMsg, wParam, lParam) 


This function posts a message to an application identified by a task han- 
dle, and then returns without waiting for the application to process the 
message. The application receiving the message obtains the message by 
calling the GetMessage or PeekMessage function. The hWnd parameter 
of the returned MSG structure is NULL. 


Parameter Type/Description 

h Task HANDLE Identifies the application that is to receive 
the message. 

wMsq unsigned Specifies the type of message posted. 

wParam WORD Specifies additional message information. 

lParam LONG Specifies additional message information. 


Return Value 


The return value specifies whether or not the message is posted. It is 
nonzero if the message is posted. Otherwise, it is zero. 


BOOL PostMessage(hWnd, wMsg, wParam, lParam) 


This function places a message in a window’s application queue, and then 
returns without waiting for the corresponding window to process the mes- 
sage. The posted message can be retrieved by calls to the GetMessage or 
Peek Message function. 
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Parameter Type/ Description 


hWnd HWND _Identifies the window to receive the message. 
If the hWnd parameter is FFFF (hexadecimal), the mes- 
sage is sent to all overlapped or pop-up windows in the 
system. The message is not sent to child windows. 


wMsq unsigned Specifies the type of message posted. 
wParam WORD _ Specifies additional message information. 
lParam LONG Specifies additional message information. 


Return Value 


The return value specifies whether or not the message is posted. It is 
nonzero if the message is posted. Otherwise, it 1s zero. 


Comments 


An application should never use the PostMessage function to send a 
message to a control. If a system running Windows is configured for an 
extended-memory system (EMS) and an application sends a message {by 
using the PostMessage function) with related data (that are pointed to 
by the [Param parameter) to a second application, the first application 
must place the data (that (Param points to) in global memory allocated 
with the GlobalAlloc function and the GMEM_LOWER flag. Note 
that this allocation of memory is necessary only if (Param contains a 
pointer. 


void PostQuitMessage(nExitCode) 


This function informs Windows that the application wishes to terminate 
execution. It is typically used in response to a WM_ DESTROY message. 


The PostQuitMessage function posts a WM_ QUIT message to the appli- 
cation and returns immediately; the function merely informs the system 
that the application wants to quit sometime in the future. 


When the application receives the WM_. QUIT message, it should exit the 
message loop in the main function and return control to Windows. The 
exit code returned to Windows must be the wParam parameter of the 


WM_ QUIT message. 
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Parameter Type/Description 


nEntCode int Specifies an application exit code. It 1s used as the 
wParam parameter of the WM_ QUIT message. 


Return Value 


None 


BOOL PtiInRect(/pRect, Point) 


This function specifies whether the specified point lies within a given rect- 
angle. A point is within a rectangle if it hes on the left or top side, or is 
within all four sides. A point on the right or bottom side is outside the 
rectangle. 


Parameter Type/Description 

lpRect LPRECT Points toa RECT data structure that 
contains the specified rectangle. 

Point POINT § Specifies a POINT data structure that 


contains the specified point. 


Return Value 
The return value specifies whether the specified point hes within the given 


rectangle. It is nonzero if the point lies within the given rectangle. Other- 
wise, 1t is zero. 


BOOL PtInRegion(hRgn, X, Y) 


This function specifies whether the point given by the X and Y parameters 
is in the given region. 


Parameter Type/Description 

hRgn HRGN Identifies the region to be examined. 

xX short Specifies the logical 2-coordinate of the point. 
Y short Specifies the logical ycoordinate of the point. 


395 


PtInRegion 


Return Value 


The return value specifies whether the specified point is in the given 
region. It is nonzero if the point is in the region. Otherwise, it 1s zero. 


BOOL PtVisible(hDC, X, Y) 


This function specifies whether the given point is within the clipping 
region of the specified device context. 


Parameter Type/ Description 

hDC HDC Identifies the device context. 

xX short Specifies the logical #coordinate of the point. 
Y short Specifies the logical ycoordinate of the point. 


Return Value 
The return value specifies whether the specified point is within the clipping 


region of the given display context. It is nonzero if the point 1s within the 
clipping region. Otherwise, it 1s zero. 
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short ReadComm(nCid, lpBuf, nSize) 


This function reads the number of characters specified by the nSzze param- 
eter from the communication device specified by the nCid parameter and 
copies the characters into the buffer pointed to by the [pBuf parameter. 


Parameter Type/Description 
nCid int Specifies the communication device to be read. 
lnBuf LPSTR Points to the buffer that is to receive the 


characters read. 


nSize int Specifies the number of characters to be read. 


Return Value 


The return value specifies the number of characters actually read. It is less 
than the number specified by nSize only if the number of characters in the 
receive queue is less than that specified by nSize. If it is equal to nSize, 
additional characters may be queued for the device. If the return value is 
zero, no characters are present. 


When an error occurs, the return value is set to a value less than zero, 
with the absolute value being the actual number of characters read. The 
cause of the error can be determined by using the GetCommError func- 
tion to retrieve the error code and status. Since errors can occur when no 
bytes are present, if the return value is zero, the GetCommError func- 
tion should be used to ensure that no error occurred. 


For parallel I/O ports, the return value will always be zero. 


BOOL Rectangle(hDC, X1, Y1, X2, Y2) 


This function draws a rectangle. The interior of the rectangle is filled by 
using the selected brush, and a border is drawn with the selected pen. 


Parameter Type/ Description 
hDC HDC = Identifies the device context. 
X1 short Specifies the logical coordinate of the upper- 


left corner of the rectangle. 


Y1 short Specifies the logical y-coordinate of the upper- 
left corner of the rectangle. 
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X2 short Specifies the logical xcoordinate of the lower- 
right corner of the rectangle. 


pe2 short Specifies the logical y coordinate of the lower- 
right corner of the rectangle. 


Return Value 


The return value specifies whether the rectangle is drawn. It is nonzero 
if the rectangle is drawn. Otherwise, It is zero. 


Comments 


The width of the rectangle specified by the X1, Y1, X2, and Y2 parameters 
must not exceed 32,767 units. This limit applies to the height of the rect- 
angle as well. 


The current position is neither used nor updated by this function. 


BOOL RectVisible(hDC, lpRect) 


This function determines whether any part of the given rectangle lies 
within the clipping region of the specified display. 


Parameter Type/Description | 

hDC HDC | Identifies the device context. 

IpRect LPRECT Points toa RECT data structure that 
contains the logical coordinates of the specified rect- 
angle. 


Return Value 


The return value specifies whether the rectangle is within the clipping 
region. It is nonzero if some portion of the given rectangle lies within the 
clipping region. Otherwise, it is zero. 


BOOL RegisterClass(/p WndClass) 


This function registers a window class for subsequent use in calls to the 
CreateWindow function. The window class has the attributes defined 
by the contents of the data structure pointed to by the lp WndClass 
parameter. 
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If two classes with the same name are registered, the most recently 
registered class is recognized; the other is ignored. 


Parameter Type/ Description 


lp WndClass LPWNDCLASS Points toa WNDCLASS data 
structure. The structure must be filled with the 
appropriate class attributes before being passed to the 
as See the following “Comments” section for 
etails. 


Return Value 


The return value specifies whether the window class is registered. It is 
nonzero if the class 1s registered. Otherwise, it is zero. 


Comments 


To avoid conflicts with the class names of other applications, it is a good 
idea to use a derivation of the application’s module name (from the .def 
file) for the window class name. 


The callback function must use the Pascal calling conventions and must be 
declared FAR. The function must have the following form: 


BOOL FAR PASCAL WndProc(hWnd, wMsg, wParam, lParam) 
HWND jAWhd; 

unsigned wMsq; 

WORD wParam; 

DWORD /Param; 


WndProc is a placeholder for the application-supplied function name. The 
actual name must be exported by including it in an EXPORTS state- 
ment in the application’s module-definition file. 


Parameter Description 

hWnd Identifies the window that receives the message. 
wMsq Specifies the message number. 

wParam Specifies additional message-dependent information. 
lParam Specifies additional message-dependent information. 
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Return Value 


The window function returns the result of the message processing. The 
possible return values depend on the actual message sent. 


WORD RegisterClipboardFormat(lpFormatName) 


This function registers a new clipboard format whose name is pointed to 
by the lpFormatName parameter. The registered format can be used in 
subsequent clipboard functions as a valid format in which to render data, 
and it will appear in the clipboard’s list of formats. 


Parameter Type/Description 


lpFormatName LPSTR Points to a character string that names the 
new format. The string must be a null-terminated char- 
acter string. 


Return Value 


The return value specifies the newly registered format. If the identical for- 
mat name has been registered before, even by a different application, the 
format’s reference count is increased and the same value is returned as 
when the format was originally registered. The return value is zero if the 
format cannot be registered. | 


Comments 


The format value returned by the RegisterClipboardMessage function 
is in the range COO0 to FFFF (hexadecimal). 


WORD Register WindowMessage(IpString) 


This function defines a new window message that is guaranteed to be 
unique throughout the system. The returned message value can be used 
when calling the SendMessage or PostMessage function. 


Register WindowMessage is typically used for communication between 
two cooperating applications. 


If the same message string is registered by two different applications, the 


same message value is returned. The message remains registered until the 
user ends the Windows session. 
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Parameter Type/Description 


lnString LPSTR Points to the message string to be registered. 


Return Value 
The return value specifies the outcome of the function. It is an unsigned 


short integer in the range CO00 to FFFF (hexadecimal) if the message is 
successfully registered. Otherwise, it is zero. 


Comments 
Register WindowMessage need only be used when the same message 
must be understood by more than one application. For sending private 


messages within an application, an application can use any integer in 
the range WM_ USER to BFFF (hexadecimal). 


void ReleaseCapture( ) 

This function releases the mouse capture and restores normal input pro- 
cessing. A window with the mouse capture receives all mouse input regard- 
less of the position of the mouse cursor. 


This function has no parameters. 


Return Value 


None 


int ReleaseDC(hWnd, hDC) 


This function releases a device context, freeing it for use by other appli- 
cations. The effect of the ReleaseDC function depends on the device- 
context type. It frees only common and window device contexts. It has no 
effect on class or private device contexts. 
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Parameter Type/Description 

hWnd HWND Identifies the window whose device context 1s 
to be released. 

hDC HDC Identifies the device context to be released. 


Return Value 


The return value specifies whether the device context is released. It is 1 if 
the device context is released. Otherwise, it 1s zero. 


Comments 


The application must call the ReleaseDC function for each call to the 
GetWindowDC function and for each call to the GetDC function that 
retrieves a common device context. 


BOOL RemoveFontResource(lpFilename) 


This function removes an added font resource from the file named by the 
loFilename parameter or from the Windows font table. 


Parameter Type/Description 


lpFilename LPSTR Points to a string that names the font- 
resource file or contains a handle to a loaded module. 
If IpFilename points to the font-resource filename, the 
string must be null-terminated, have the DOS filename 
format, and include the extension. If lpFilename con- 
tains a handle, the handle must be in the low-order 
word; the high-order word must be zero. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
function is successful. Otherwise, it is zero. 


Comments 


Any application that adds or removes fonts from the Windows font 
table should notify other windows of the change by using the 
SendMessage function to send the WM_ FONTCHANGE message. 
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This message should be sent to all window handles enumerated by 
the Enum Windows function. 


The RemoveFontResource function may not actually remove the font 
resource. If there are outstanding references to the resource, the font 
resource remains loaded until the last referencing logical font has been 
deleted by using the DeleteObject function. 


HANDLE RemoveProp(hWnd, lpString) 


This function removes an entry from the property list of the specified 
window. The character string specified by the [pString parameter identifies 
the entry to be removed. 


The RemoveProp function returns the data handle associated with the 
string so that the application can free the data associated with the handle. 


Parameter Type/Description 


hWnd HWND Identifies the window whose property list is 
to be changed. 


lynString LPSTR Points to a null-terminated character string 
or to an atom that identifies a string. If an atom is 
given, it must have been previously created by means of 
the AddAtom function. The atom, a 16-bit value, must 
be placed in the low-order word of IpString; the high- 
order word must be zero. 


Return Value 


The return value identifies the given string. It is NULL if the string cannot 
be found in the given property list. 


Comments 


The application must free the data handles associated with entries 
removed from a property list. 


void ReplyMessage(/Reply) 


This function 1s used to reply to a message that was sent through the 
SendMessage function, without returning control to the function that 
called SendMessage. Ordinarily, SendMessage waits for the return 
value of the function to which the message was sent. The ReplyMessage 
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function allows the function that receives the message to send back a 
value without returning. 


The ReplyMessage function has no effect if the message was not sent 
through the SendMessage function. 


Parameter Type/Description 


lReply long Specifies the result of the message processing. 
The possible values depend on the actual message sent. 


Return Value 


None 


BOOL RestoreDC(hDC, nSavedDC) 


This function restores the device context specified by the hDC param- 
eter to the previous state identified by the nSavedDC parameter. The 
RestoreDC function restores the device context by copying state infor- 
mation saved on the context stack by earlier calls to the SaveDC func- 
tion. 


The context stack can contain the state information for several device 
contexts. If the context specified by nSavedDC 1s not at the top of the 
stack, RestoreDC deletes any state information between nSavedDC 
and the top of the stack. The deleted information is lost. 


Parameter Type/ Description 
hDC HDC Identifies the device context. 
nSavedDC short Specifies the device context to be restored. It 


can be a value returned by a previous SaveDC call. If 
nSavedDC' is —1, the most recent device context saved 
is restored. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
specified context is restored. Otherwise, it is zero. 
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DWORD RGB(cRed, cGreen, cBlue) 


This macro selects an RGB color based on the parameters supplied and the 
color capabilities of the output device. 


Parameter Type/ Description 

cRed | BYTE § Specifies the intensity of the red color field. 
cGreen BYTE § Specifies the intensity of the green color field. 
cBlue BYTE Specifies the intensity of the blue color field. 


Return Value 


The return value specifies the resultant RGB color. 


Comments 


The intensity for each argument can range from 0 to 255. If all three 
intensities are specified as O, the result is black. If all three intensities 
are specified as 255, the result is white. 


BOOL RoundRect(hDC, X1, Y1, X2, Y2, X8, Y9) 


This function draws a rectangle with rounded corners. The interior of the 
rectangle is filled by using the selected brush, and a border is drawn with 
the selected pen. 


Parameter Type/Description 
hDC HDC _ Identifies the device context. 
XI short Specifies the logical z-coordinate of the upper- 


left corner of the rectangle. 


Y1 short Specifies the logical ycoordinate of the upper- 
left corner of the rectangle. 


X2 short Specifies the logical zcoordinate of the lower- 
right corner of the rectangle. 


Y2 short Specifies the logical ycoordinate of the lower- 
right corner of the rectangle. 
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X38 short Specifies the width of the ellipse used to draw 
the rounded corners. 
Y3 short Specifies the height of the ellipse used to draw 


the rounded corners. 


Return Value 


The return value specifies whether the rectangle is drawn. It is nonzero if 
the rectangle is drawn. Otherwise, it 1s zero. 


Comments 

The width of the rectangle specified by the XJ, Y1, X2, and Y2 parameters 
must not exceed 32,767 units. This limit applies to the height of the rect- 
angle as well. 


The current position is neither used nor updated by this function. 
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short SaveDC(hDC) 
This function saves the current state of the device context specified by the 
hDC parameter by copying state information (such as clipping region, 


selected objects, and mapping mode) to a context stack. The saved device 
context can later be restored by using the RestoreDC function. 


Parameter Type/Description 


hDC HDC Identifies the device context to be saved. 


Return Value 


The return value specifies the saved device context. It is zero if an error 
occurs. 


Comments 


The SaveDC function can be used any number of times to save any 
number of device-context states. 


DWORD ScaleViewportExt(hDC, Xnum, Xdenom, Ynum, Ydenom) 


This function modifies the viewport extents relative to the current values: 
The formulas are written as follows: 


xNewVE = (xOldVE X Xnum) / Xdenom 
yNewVE = (yOldVE x Ynum) / Ydenom 


The new extent is calculated by multiplying the current extents by the 
given numerator and then dividing by the given denominator. 


Parameter Type/Description 
ADC HDC Identifies the device context. 
Xnum short Specifies the amount by which to multiply the 


current a-extent. 


Xdenom short Specifies the amount by which to divide the 
current zextent. 


Ynum short Specifies the amount by which to multiply the 
current yextent. 


Ydenom short Specifies the amount by which to divide the 
current yextent. 
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Return Value 


The return value specifies the previous viewport extents (in device units). 
The previous y-extent is in the high-order word; the previous 2-extent 1s 
in the low-order word. ce 


DWORD ScaleWindowExt(hDC, Xnum, Xdenom, Ynum, Ydenom) 


This function modifies the window extents relative to the current values. 
The formulas are written as follows: 


xNewWE = (xOldWE X Xnum) / Xdenom 
yNewWE = (yOIGWE X Ynum) / Ydenom 


The new extent is calculated by multiplying the current extents by the 
given numerator and then dividing by the given denominator. 


Parameter Type/Description 
ADC HDC Identifies the device context. 
Xnum short Specifies the amount by which to multiply the 


current z-extent. 


Xdenom short Specifies the amount by which to divide the 
current zextent. 


Ynum short Specifies the amount by which to multiply the 
current yextent. 


Ydenom short Specifies the amount by which to divide the 
current y-extent. 


Return Value 


The return value specifies the previous window extents (in logical units). 
The previous yextent is in the high-order word; the previous 2-extent is 
in the low-order word. 


void ScreenToClient(hWnd, IpPoint) 


This function converts the screen coordinates of a given point on the 
display to client coordinates. The Screen ToClient function uses the win- 
dow given by the hWnd parameter and the screen coordinates given in the 
POINT data structure pointed to by the /pPoint parameter to compute 
client coordinates, and then replaces the screen coordinates with the client 
coordinates. The new coordinates are relative to the upper-left corner of 
the given window’s client area. 
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Parameter Type/Description 

hWnd HWND Identifies the window whose client area will 
be used for the conversion. 

lnPotnt LPPOINT Points to a POINT data structure that 


contains the screen coordinates to be converted. 


Return Value 


None 


Comments 


The ScreenToClient formula assumes the given point is in screen 
coordinates. 


BOOL ScrollIDC(hDO, dz, dy, lpreScroll, lpreClip, hrgnUpdate, lprcUpdate) 


This function scrolls a rectangle of bits horizontally and vertically. The 
lorcScroll parameter points to the rectangle to be scrolled, the dx parame- 
ter specifies the number of units to be scrolled horizontally, and the dy 
parameter specifies the number of units to be scrolled vertically. 


Parameter Type/Description 

hDC HDC Identifies the device context that contains the 
bits to be scrolled. 

dx int Specifies the number of horizontal scroll units. 

dy int Specifies the number of vertical scroll units. 

lorcScroll LPRECT Points to the RECT data structure that 
contains the coordinates of the scrolling rectangle. 

lorcClip LPRECT Points to the RECT data structure that 


contains the coordinates of the clipping rectangle. When 
this rectangle is smaller than the original pointed to by 
lorcScroll, scrolling occurs only in the smaller rectangle. 


hrgnUpdate HRGN Identifies the region uncovered by the scroll- 
ing process. The ScrolIDC function defines this region; 
it is not necessarily a rectangle. 


lorcUpdate LPRECT Points to the RECT data structure that, 
upon return, contains the coordinates of the rectangle 
that bounds the scrolling update region. This is the larg- 
est rectangular area that requires repainting. 
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Return Value 


This value specifies the outcome of the function. It is nonzero if scrolling is 
executed. Otherwise, it is zero. 


Comments 


If either the hrgnUpdate or IprcUpdate parameter is NULL, Windows does 
not compute the update rectangle. If hgnUpdate is not NULL, Windows 
assumes that it contains a valid region handle to the region uncovered by 
the scrolling process (defined by the ScrollIDC runcton), 


An application should use the ScrollWindow function when it is neces- 
sary to scroll the entire client area of a window; otherwise, it should use 


ScrollDC. 


void ScrollWindow(hWnd, XAmount, YAmount, lpRect, lpClipRect) 


This function scrolls a window by moving the contents of the window’s 
client area the number of units specified by the XAmount parameter along 
the screen’s 2-axis and the number of units specified by the YAmount 
parameter along the y-axis. The scroll moves right if XA mount is positive 
and left if it is negative. The scroll moves down if YAmount is positive and 
up if it is negative. 


Parameter Type/Description 


hWnd HWND Identifies the window whose client area is to 
be scrolled. 


XAmount int Specifies the amount (in device units) to scroll in 
the x direction. 

YAmount int Specifies the amount (in device units) to scroll in 
the y direction. 

lpRect LPRECT Points toa RECT data structure that 


specifies the portion of the client area to be scrolled. If 
loRect is NULL, the entire client area is scrolled. 


lpClipRect LPRECT Points toa RECT data structure that 
specifies the clipping rectangle to be scrolled. Only bits 
inside this rectangle are scrolled. If lpClipRect is NULL, | 
the entire window is scrolled. ae 
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Return Value 


None 


Comments 


If the caret is in the window being scrolled, ScrollWindow automatically 
hides the caret to prevent it being erased, then restores the caret after the 
scroll is finished. The caret position is adjusted accordingly. 


The area uncovered by the ScrollWindow function is not repainted, but 
is combined into the window’s update region. The application will eventu- 
ally receive a WM. PAINT message notifying it that the region needs 
repainting. To repaint the uncovered area at the same time the scrolling 
is done, call the UpdateWindow function immediately after calling 
ScrollWindow. 


If the IpRect parameter is NULL, the positions of any child windows in the 
window are offset by the amount specified by XAmount and YAmount, 

and any invalid (unpainted) areas in the window are also offset. Scroll- 
Window is somewhat faster when [pRect is NULL. 


If the lpRect parameter is not NULL, the positions of child windows are 
not changed, and invalid areas in the window are not offset. To prevent 
updating problems when IpRect is not NULL, calling the UpdateWindow 
function to repaint the window before calling ScrollWindow is recom- 
mended. 


short SelectClipRgn(hDC, hRgn) 


This function selects the given region as the current clipping region for the 
specified device context. Only a copy of the selected region is used. The 
region itself can be selected for any number of other device contexts, or it 
can be deleted. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
hRgn HRGN Identifies the region to be selected. 
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Return Value 


The return value specifies the region’s type. It can be any one of the fol- 
lowing values: 


COMPLEXREGION New clipping region has overlapping a 
borders. 

ERROR Device context or region handle is not valid. 

NULLREGION New clipping region is empty. 

SIMPLEREGION New clipping region has no overlapping 
borders. 

Comments 


The SelectClipRgn function assumes that the coordinates for the given 
region are specified in device units. 


HANDLE SelectObject(hDC, hObject) 


This function selects the logical object specified by the hObject parameter 
as the selected object of the specified device context. The new object 
replaces the previous object of the same type. For example, if hObject is 
the handle to a logical pen, the SelectObject function replaces the 
selected pen with the pen specified by hObject. 


Selected objects are the default objects used by the GDI output functions 
to draw lines, fill interiors, write text, and clip output to specific areas of 
the device surface. Although a device context can have five selected objects 
(pen, brush, font, bitmap, and region), no more than one object of any 
given type can be selected at one time. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
hObject HANDLE Identifies the object to be selected. 


It may be any one of the following, and must 
have been created by using one of the following 
functions: 
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Object Function 
Bitmap CreateBitmap 
CreateBitmapIndirect 


CreateCompatibleBitmap 


Bitmaps can be selected for memory 
device contexts only, and for only 
one device context at a time. 


Brush CreateBrushIndirect 
CreateHatchBrush 
CreatePatternBrush 
CreateSolidBrush 


Font CreateF ont 
CreateF ontIndirect 


Pen CreatePen 
CreatePenIndirect 


Region CombineRgn 
CreateEllipticRgn 
CreateEllipticRgnIndirect 
CreatePolygonRgn 
CreateRectRgn 
CreateRectRgnIndirect 


Return Value 


The return value identifies the object being replaced by hObject. It is 
NULL if there is an error. 


If the hDC parameter specifies a metafile, the return value is nonzero if 
the function is successful. Otherwise, it is zero. 


Comments 

When you select a font, pen, or brush by using the SelectObject func- 
tion, GDI allocates space for that object in its data segment. Because 
data-segment space is limited, you should use the DeleteObject function 
to delete each drawing object that you no longer need. 


When you have deleted the last of the unneeded drawing objects, you 
should select the original (default) object back into the device context. 


You cannot select a bitmap into more than one device context at any time. 
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long SendDlgItemMessage(hDlg, nIDDigltem, wMsg, wParam, lParam) 


This function sends a message to the control specified by the nJDDigItem 
parameter within the dialog box specified by the hDlg parameter. The 
SendDlgItemMessage function does not return until the message has 
been processed. 


Parameter Type/Description 

hDig HWND Identifies the dialog box that contains the 
control. 

nIDDigltem int Specifies the integer identifier of the dialog item 
that is to receive the message. 

wMsgq unsigned Specifies the message value. 

wParam WORD Specifies additional message information. 

[Param long Specifies additional message information. 


Return Value 


The return value specifies the outcome of the function. It is the value 
returned by the control’s window function, or zero if the control identifier 
is not valid. 


Comments 


Using SendDlgItemMessage is identical to obtaining a handle to the 
given control and calling the SendMessage function. 


long SendMessage(hWnd, wMsg, wParam, lParam) 


This function sends a message to a window or windows. The 
SendMessage function does not return until the message has been pro- 
cessed. If the window that receives the message is part of the same applica- 
tion, the window function is called immediately as a subroutine. If the 
window is part of another task, Windows switches to the appropriate task 
and calls the appropriate window function, and then passes the message 

to the window function. The message is not placed in the destination 
application’s queue. 
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Parameter Type/Description 


hWnd HWND Identifies the window that is to receive the 
message. If the hWnd parameter is FFFF (hexadecimal), 
the message is sent to all pop-up windows in the system. 
The message is not sent to child windows. 


wMsg unsigned Specifies the message to be sent. 
wParam WORD Specifies additional message information. 
lParam long Specifies additional message information. 


Return Value 


The return value specifies the outcome of the function. It is the value 
returned by the window function that received the message; its value 
depends on the message being sent. 


Comments 


If a system running Windows is configured for extended memory oe) 
and an application sends a message (by using the SendMessage function) 
with related data (that is pointed to by the [Param parameter) to a second 
application, the first application must place the data (that [Param points 
to) in global memory allocated by the GlobalAlloc function and the 
GMEM_ LOWER flag. Note that this allocation of memory is only neces- 
sary if [Param contains a pointer. 


HWND SetActiveWindow(hWnd) 
This function makes a pop-up window the active window. If the window 


specified by the hWnd parameter does not currently have the input focus, 
the focus is set to NULL (input is ignored). 


Parameter Type/Description 
hWnd HWND identifies the pop-up window to be activated. 


Return Value 


The return value identifies the window that was previously active. The 
SetActiveWindow function should be used with care since it allows an 
application to arbitrarily take over the active window and input focus. 
Normally, Windows takes care of all activation. 
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long SetBitmapBits(hBitmap, dwCount, lpBits) 


This function sets the bits of a bitmap to the bit values given by the /pBits 
parameter. 


Parameter Type/ Description 

hBitmap HBITMAP Identifies the bitmap to be set. 

dwCount DWORD Specifies the number of bytes pointed to by 
lnBits. 

ln Bits LPSTR Points to the bitmap bits that are stored as 


an array of short integers. 


Return Value 


The return value specifies the number of bytes used in setting the bitmap 
bits. It is zero if the function fails. 


DWORD SetBitmapDimension(hBitmap, X, Y) 


This function assigns a width and height to a bitmap in 0.1-milli- 
meter units. These values are not used internally by GDI; the 
GetBitmapDimension function can be used to retrieve them. 


Parameter Type/ Description 

hBitmap HANDLE Identifies the bitmap. 

X short Specifies the width of the bitmap 
(in 0.1-millimeter units). 

4g short Specifies the height of the bitmap 


(in 0.1-millimeter units). 


Return Value 


The return value specifies the previous bitmap dimensions. Height is in the 
high-order word, and width is in the low-order word. 


DWORD SetBkColor(hDC, rgbColor) 
This function sets the current background color to the color specified by 


the rgbColor parameter, or to the nearest logical color if the device cannot 
represent the color specified by rgbColor. 
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If the background mode is OPAQUE, GDI uses the background color to fill 
the gaps between styled lines, gaps between hatched lines in brushes, and 
character cells. GDI also uses the background color when converting bit- 
maps from color to monochrome and vice versa. 


The background mode is set by the SetBkMode function. See the BitBlt 
and StretchBlt functions, in this chapter, for color-bitmap conversions. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


rgbColor DWORD Specifies an RGB color value for the new 
background color. 


Return Value 


The return value specifies the previous background color as an RGB color 
value. If an error occurs, the return value is 8S0000000H (hexadecimal). 


short SetBkMode(hDC, nBkMode) 


This function sets the background mode used with text, hatched brushes, 
and line styles. The background mode defines whether or not GDI should 
remove existing background colors on the device surface before drawing 
text, hatched brushes, or any pen style that is not a solid line. 


Parameter Type/ Description 
hDC HDC Identifies the device context. 
nBkMode short Specifies the background mode. It can be either 


one of the following modes: 


Value Meaning 


OPAQUE Background is filled with the current 
background color before the text, 
hatched brush, or pen is drawn. 


TRANSPARENT 


Background remains untouched. 


Return Value 


The return value specifies the previous background mode. It can be either 


OPAQUE or TRANSPARENT. 
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DWORD SetBrushOrg(hDC, X, Y) 


This function sets the origin of all selected brushes into the given device 
context. 


Parameter Type/ Description 

hDC HDC Identifies the device context. 

X short Specifies the coordinate (in device units) of the 
new origin. 

Y- short Specifies the ycoordinate (in device units) of the 
new origin. 


Return Value 
The return value specifies the origin of the brush. The previous %coor- 


dinate is in the low-order word, and the previous y- coordinate is in the 
high-order word. 


Comments 
‘The original brush origin is at the coordinate (0,0). 


The SetBrushOrg function should not be used with stock objects. 


HWND SetCapture(hWnd) 
This function causes all subsequent mouse input to be sent to the window 


specified by the hWnd parameter, regardless of the position of the mouse 
cursor. 


Parameter Type/Description 


hWnd HWND _sIdentifies the window that is to receive the 
mouse input. 


Return Value 


The return value identifies the window that previously received all mouse 
input. It is NULL if there is no such window. 
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void SetCaretBlink Time(wMSeconds) 


This function sets the caret blink rate (elapsed time between caret flashes) 
to the number of milliseconds specified by the wMSeconds parameter. The 
caret flashes on or off each wMSeconds milliseconds. This means one com- 

plete flash (on-off-on) takes 2X wMSeconds milliseconds. 


Parameter Type/Description 
wMSeconds WORD Specifies the new blink rate (in milli- 
seconds). 


Return Value 
None 


Comments 


The system caret is a shared resource. A window should set the caret blink 
rate only if it owns the caret. It should restore the previous rate before it 
loses the input focus or becomes inactive. 


void SetCaretPos(X, Y) 


This function moves the caret to the position given by logical coordinates 
specified by the X and Y parameters. Logical coordinates are relative to 
the client area of the window that owns them and are affected by the 
window’s mapping mode, so the exact position in pixels depends on this 
Mapping mode. 


The SetCaretPos function moves the caret only if it is owned by a win- 
dow i in the current task. SetCaretPos moves the caret whether or not the 
caret is hidden. 


Parameter Type/Description 


x int Specifies the new zcoordinate (in logical 
coordinates) of the caret. 


Y int Specifies the new ycoordinate (in logical 
coordinates) of the caret. 
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Return Value 


None 


Comments 


The system caret is a shared resource. A window should not move the 
caret if it does not own the caret. 


LONG SetClassLong(hWnd, nIndex, INewLong) 


This function replaces the long value specified by the n/ndez parameter in 
the WNDCLASS data structure of the window specified by the hWnd 
parameter. 


Parameter Type/Description 
hWnd HWND Identifies the window. 
nindex int Specifies the word to be changed. It must be one of 


the following values: 


Value Meaning 
GCL. MENUNAME Sets a new long pointer to the 
menu name. 


GCL._WNDPROC _ Sets a new long pointer to the 
window function. 


INewLong LONG Specifies the replacement value. 
Return Value 


The return value specifies the previous value of the specified long integer. 


Comments 


If the SetClassLong function and GCL. WNDPROC index are used to set 
a, window function, the given function must have the window-function 
form and be exported in the module-definition file. See the RegisterClass 
function earlier in this chapter for details. 
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WORD SetClassWord(hWnd, nIndez, wNew Word) 


This function replaces the word specified by the nJndez parameter in the 
WNDCLASS structure of the window specified by the hWnd parameter. 


Parameter Type/Description 
hWnd HWND Identifies the window. 
nindex int Specifies the word to be changed. It must be one of 


the following values: 
Value Meaning 


GCW.. CBCLSEXTRA 
Sets two new bytes of additional 
window-class data. 


GCW_ CBWNDEXTRA 
Sets two new bytes of additional 
window-class data. 


GCW. HBRBACKGROUND 
Sets a new handle to a background 


brush. 
GCWW— HCURSOR _ Sets a new handle to a cursor. 
GCW-. HICON Sets a new handle to an icon. 
GCW.HMODULE | Sets a new handle to a module. 
GCW_ STYLE Sets a new style bit for the window 


class. 
wNewWord WORD Specifies the replacement value. 
Return Value 


The return value specifies the previous value of the specified word. 


Comments 


The SetClass Word function should be used with care. For example, it is 
possible to change the background color for a class by using SetClass- 
Word, but this change does not cause all windows belonging to the class 
to be repainted immediately. 
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HANDLE SetClipboardData(wFormat, hMem) 


This function sets a data handle to the clipboard for the data specified by 

the hMem parameter. The data are assumed to have the format specified 

by the wKormat parameter. After setting a clipboard data handle, the 

SetClipboardData function frees the block of memory identified by a 


hMem. 
Parameter Type/Description 
wkormat WORD Specifies a data format. It can be any one of 


the predefined formats given in Table 3.14. 


In addition to the predefined formats, any format value 
registered through the Register ClipboardFormat 
function can be used as the wFormat parameter. 


hMem HANDLE Identifies the global memory block that 
contains the data in the specified format. The hMem 
parameter can be NULL. When hMem is NULL the 
application does not have to format the data and pro- 


vide a handle to it until requested to do so through a 
WML RENDERFORMAT message. 


Return Value 

The return value identifies the data and is assigned by the clipboard. 
Comments 

Once the hMem parameter has been passed to SetClipboardData, the 
block of data becomes the property of the clipboard. The application may 
read the data, but should not free the block or leave it locked. 


Table 3.14 shows the predefined data formats for the wFormat parameter: 
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SetClipboardData 


Predefined Data Formats 


Value 
CF_ BITMAP 


CF_ DIF 
CF_ DSPBITMAP 


CF_ DSPMETAFILEPICT 


CF_ DSPTEXT 


CF_ METAFILEPICT 


CF_ OWNERDISPLAY 


CF_PRIVATEFIRST to 
CF_ PRIVATELAST 


CF_SYLK 
CF_ TEXT 


Meaning 


Bitmap as defined by the BITMAP data 


structure. 
software Arts’ Data Interchange Format. 


Bitmap display format associated with private 
format. The hMem parameter must be a handle 
to data that can be displayed in bitmap format 
in lieu of the privately formatted data. 


Metafile-picture display format associated with 

private format. The hMem parameter must be a 

handle to data that can be displayed in metafile- 

oe format in leu of the privately formatted 
ata. 


Text display format associated with private 
format. The hMem parameter must be a handle 
to data that can be displayed in text format in 
heu of the privately formatted data. 


Metafile picture format as defined by the 
METAFILEPICT data structure. 


Owner display format. The clipboard owner 
must display and update the clipboard 
application window, and will receive 

WM_ ASKCBFORMATNAME, 

WM. HSCROLLCLIPBOARD, 

WM_ PAINTCLIPBOARD, 

WM_ SIZECLIPBOARD, and 
WM_VSCROLLCLIPBOARD messages. 
The hMem parameter must be NULL. 


Range of integer values used for private for- 
mats. Data handles associated with formats in 
this range will not be freed automatically; any 
data handles must be freed by the application 
before the application terminates or when a 
WM. DESTROYCLIPBOARD message is 


received, 
Microsoft Symbolic Link (SYLK) format. 


Text format. Each line ends with a carriage 
return/linefeed (CR-LF) combination. A null 
character signals the end of the data. 
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HWND SetClipboardViewer(hWnd) 
This function adds the window specified by the hWnd parameter to the 


chain of windows that are notified (via the WM_DRAWCLIPBOARD 
message) whenever the contents of the clipboard are changed. 


Parameter Type/Description 


hWnd HWND Identifies the window to receive clipboard- 


viewer chaln messages. 


Return Value 
The return value identifies the next window in the clipboard-viewer chain. 


This handle should be saved in static memory and used in responding to 
clipboard-viewer chain messages. 


Comments 

Windows that are part of the clipboard-viewer chain must respond 
to WM_ CHANGECBCHAIN, WM DRAWCLIPBOARD, and 
WM_ DESTROY messages. 


If an application wishes to remove itself from the clipboard-viewer chain, 
it must call the ChangeClipboardChain function. 


short SetCommBreak(nCid) 


This function suspends character transmission and places the transmission 
line in a break state until the ClearCommBreak function is called. 


Parameter Type/Description 


nCid int Specifies the communication device to be 
suspended. 


Return Value 


The return value specifies the result of the function. It is zero if the func- 
tion is successful. It is negative if nCzd does not specify a valid device. 
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WORD FAR * SetCommEventMask(nCid, nEvtMask) 


This function enables and retrieves the event mask of the communication 
device specified by the nCid parameter. The bits of the nEvitMask parame- 
ter define which events are to be enabled. The return value points to the 
current state of the event mask. 


Parameter Type/Description 
nCid int Specifies the communication device to be enabled. 
niviMask int Specifies which events are to be enabled. It can be 


any combination of the values shown in Table 3.15. 


Return Value 
The return value points to the event mask, an integer. Each bit in the 


event mask specifies whether or not a given event has occurred. A bit 
is 1 if the event has occurred. 


Comments 


Table 3.15 lists the event values for the nEvtMask parameter: 


Table 3.15 

Event Values 

Value Meaning 

EV... BREAK Sets when a break is detected on input. 

EV..CTS Sets when the clear-to-send (CTS) signal changes state. 

EV_ DSR Sets when the data-set-ready (DSR) signal changes state. 

EV_ ERR Sets when a line-status error occurs. Line-status errors are 
CE_ FRAME, CE. OVERRUN, and CE_- RXPARITY. 

EV_ PERR Sets when a printer error is detected on a parallel device. 
Errors are CE_ DNS, CE_ IOE, CE_ LOOP, and CE_ PTO. 

EV_ RING Sets when a ring indicator is detected. 

EV_ RLSD Sets when the receive-line-signal-detect (RLSD) signal 


changes state. 


EV_ RXCHAR Sets when any character is received and placed in the receive 
queue. 


EV. RXFLAG Sets when the event character is received and placed in the 
receive queue. The event character is specified in the device’s 
control block. 


EV. TXEMPTY — Sets when the last character in the transmit queue is sent. 
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short SetCommState(/pDCB) 


This function sets a communication device to the state specified by the 
device control block pointed to by the IpDCB parameter. The device to be 
set must be identified by the Id field of the control block. 


This function reinitializes all hardware and controls as defined by IpDCB, 
but does not empty transmit or receive queues. 


Parameter Type/ Description 

lnDCB DCB FAR * Points to a DCB data structure that 
contains the desired communications setting for the 
device. 


Return Value 


The return value specifies the outcome of the function. It is zero if the 
function is successful. It is negative if an error occurs. 


HCURSOR SetCursor(hCursor) 

This function sets the system-cursor shape to the shape specified by the 
hCursor parameter. The cursor is set only if the new shape is different 
from the current shape. Otherwise, the function returns immediately. 
SetCursor is quite fast if hCursor is the same as the current cursor. 


If hCursor is NULL, the cursor is removed from the screen. 


Parameter Type/ Description 


hCursor HCURSOR Identifies the cursor resource. The 
resource must have been loaded previously by using 
the LoadCursor function. 


Return Value 


The return value identifies the cursor resource that defines the previous 
cursor shape. It is NULL if there is no previous shape. 


Comments 
The system cursor is a shared resource. A window that uses the cursor 


should set the shape only when the cursor is in its client area or when it is 
capturing all mouse input. In systems without a mouse, the window should 
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restore the previous cursor shape before the cursor leaves the client area or 
before the window relinquishes control to another window. 


Any application that needs to change the shape of the system cursor while 
it is in a Window must make sure the class cursor for the given window’s 
class is set to NULL. If the class cursor is not NULL, Windows restores the 
previous shape each time the mouse is moved. 


The cursor is not shown on the screen if the cursor display count is less 


than zero (that is, the HideCursor function has been called more times 
than the ShowCursor function). 


void SetCursorPos(X, Y) 
This function moves the system cursor to the screen coordinates given by 
the X and Y parameters. If the new coordinates are not within the screen 


rectangle set by the most recent ClipCursor function, Windows automat- 
ically adjusts the coordinates so that the cursor stays within the rectangle. 


Parameter Type/Description 


xX int Specifies the new 2-coordinate (in screen 
coordinates) of the cursor. 


int Specifies the new ycoordinate (in screen 
coordinates) of the cursor. 


Return Value 
None 


Comments 


The system cursor is a shared resource. A window should move the cursor 
only when the cursor is in its client area. 


void SetDigItemInt(hDig, nIDDigltem, wValue, Signed) 


This function sets the text of a control in the given dialog box to the 
string that represents the integer value given by the wValue parameter. 
The SetDlgItemInt function converts wValue to a string that consists of 
decimal digits, and then copies the string to the control. If the bSigned 
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parameter is nonzero, wValue is assumed to be signed. If wValue is signed 
and less than zero, the function places a minus sign before the first digit in 
the string. 


SetDigitemInt sends a WM. SETTEXT message to the given control. 


Parameter Type/ Description 

hDlg HWND Identifies the dialog box that contains the 
control. 

nIDDigliem int Specifies the control to be modified. 

wValue unsigned Specifies the value to be set. 

bSigned nent Specifies whether or not the integer value is 
signed. 


Return Value 


None 


void SetDlgItemText(hDig, nIDDigItem, IpString) 


This function sets the caption or text of a control in the dialog box spec- 
ified by the hDlg parameter. The SetDlgItemText function sends a 
WM.~ SETTEXT message to the given control. 


Parameter Type/Description 

hDlg HWND Identifies the dialog box that contains the 
control. 

nIDDigltem int Specifies the control whose text is to be set. 

lnString LPSTR Points to the null-terminated character string 


that is to be copied to the control. 


Return Value 


None 
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void SetDoubleClickTime(wCount) 


This function sets the double-click time for the mouse. A double-click is a 
series of two clicks of the mouse button, the second occurring within a 
specified time after the first. The double-click time is the maximum num- 
ber of milliseconds that may occur between the first and second clicks of a 
double-click. 


Parameter Type/Description 


wCount WORD Specifies the number of milliseconds that can 
occur between double-clicks. 


Return Value 


None 


Comments 


If the wCount parameter is set to zero, Windows will use the default 
double-click time of 500 milliseconds. 


The SetDoubleClick Time function alters the double-click time for all 
windows in the system. 


short SetEnvironment(lpPoriName, lpEnviron, nCount) 


This function copies the contents of the buffer specified by the IpEnviron 
parameter into the environment associated with the device attached 

to the system port specified by the lpPortName parameter. The 
SetEnvironment function deletes any existing environment. If there 

is no environment for the given port, SetEnvironment creates one. 

If the nCount parameter is zero, the existing environment is deleted 

and not replaced. 


Parameter Type/Description 

lnPortName LPSTR Points to a null-terminated character string 
that specifies the name of the desired port. 

lnEnviron LPSTR Points to the buffer that contains the new 
environment, 

nCount WORD Specifies the number of bytes to be copied. 
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Return Value 


The return value specifies the actual number of bytes copied to the 
environment. It is zero if there is an error. It is —1 if the environment is 


deleted. 


Comments 


The first field in the buffer pointed to by the lpEnviron parameter must be 
the same as that passed in the lpDeviceName parameter of the CreateDC 
function. If lpPortName specifies a null port (as defined in the win.ini file), 
the device name pointed to by lpEnviron is used to locate the desired 
environment. 


HWND SetFocus(hWnd) 


This function assigns the input focus to the window specified by the hWnd 
parameter. The input focus directs all subsequent keyboard input to the 
given window. The window, if any, that previously had the input focus 
loses it. If hWnd is NULL, keystrokes are ignored. 


The SetFocus function sends a WM_..KILLFOCUS message to the window 
that loses the input focus and a WM_SETFOCUS message to the window 
that receives the input focus. It also activates either the window that 
receives the focus or the parent of the window that receives the focus. 


Parameter Type/Description 
hWnd HWND Identifies the window to receive the keyboard 
input. 


Return Value 


The return value identifies the window that previously had the input 
focus. It is NULL if there is no such window. 


Comments 


If a window is active but doesn’t have the focus (that is, no window 

has the focus), any key pressed will produce the SYSCHAR, 
WM_SYSKEYDOWN, or WM_.SYSKEYUP message. If the VkA- MENU 
key is also pressed, the [Param parameter of the message will have bit 30 
set. Otherwise, the messages that are produced do not have this bit set. 
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void SetKeyboardState(IpKeyStaie) 


This function copies the 256 bytes pointed to by the ee parameter 
into the Windows keyboard-state table. 


Parameter Type Description 


lnKeyState BYTE FAR * Points to an array of 256 bytes that 
contains keyboard key states. 


Return Value 


None 


Comments 


For more information, see the GetKeyboardState function, earlier in 
this chapter. 


short SetMapMode(hDC, nMapMode) 


This function sets the mapping mode of the specified device context. The 
mapping mode defines the unit of measure used to transform logical units 
into device units, and also defines the orientation of the device’s # and 
yaxes. GDI uses the mapping mode to convert logical coordinates into 
the appropriate device coordinates. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
nMapMode short Specifies the new mapping mode. [t can be any 


one of the values shown in Table 3.16. 


Return Value 


The return value specifies the previous mapping mode. 


Comments 


The MM_ TEXT mode allows applications to work in device pixels, 
whose size varies from device to device. 


The MM_ HIENGLISH, MM_ HIMETRIC, MM_ LOENGLISH, 
MM_LOMETRIC, and MM_ TWIPS modes are useful for 
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applications that need to draw in physically meaningful units (such as 


inches or millimeters). 


The MM_ISOTROPIC mode ensures a 1:1 aspect ratio, which 1s useful 


when preserving the exact shape of an image is important. 


The MM_ ANISOTROPIC mode allows the + and y coordinates to be 
adjusted independently. 


Table 3.16 shows the mapping modes: 


Table 3.16 
Mapping Modes 


Value 


MM_ ANISOTROPIC 


MM_ HIENGLISH 
MML HIME'TRIC 


MM_ ISOTROPIC 


MM_ LOMETRIC 
MM_ LOENGLISH 
MM.~ TEXT 


MM. TWIPS 
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Meaning 


Logical units are mapped to arbitrary units with 
arbitrarily scaled axes. The Set WindowExt and 
Set ViewportExt functions must be used to specify 
the desired units, orientation, and scaling. 


Each logical unit is mapped to 0.001 inch. Posi- 
tive ris to the right; positive y is up. 


Each logical unit is mapped to 0.01 millimeter. Posi- 
tive zis to the right; positive y is up. 

Logical units are mapped to arbitrary units with 
equally scaled axes; that is, one unit along the 

g-axis is equal to one unit along the y-axis. The 

Set WindowExt and Set ViewportExt functions 
must be used to specify the desired units and the 
orientation of the axes. GDI makes adjustments as 
necessary to ensure that the rand y units remain the 
same size. 


Each logical unit is mapped to 0.1 millimeter. Posi- 
tive xis to the right; positive y is up. 

Each logical unit is mapped to 0.01 inch. Positive 2 
is to the right; positive y is up. 

Each logical unit is mapped to one device pixel. 
Positive 21s to the right; positive y is down. 


Each logical unit is mapped to one twentieth of a 
printer’s point (1/1440 inch). Positive a is to the right; 
positive y is up. 
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DWORD SetMapperFlags(hDC, Flag) 


This function alters the algorithm that the font mapper uses when it maps 
logical fonts to physical fonts. When the first bit in the wFlag parameter 1s 
set to one, the mapper will only select fonts whose aspect ratios match 
those of the specified device. If no fonts exist with a matching aspect ratio, 
GDI chooses an aspect ratio and selects fonts with aspect ratios that 
match the one chosen by GDI. 


Parameter Type/Description 


hDC HDC Identifies the device context that contains the 
font-mapper flag. 


wklag DWORD | Specifies an unsigned long-integer value. 
When the first bit (bit 0) of this value is set, the font 
mapper attempts to match aspect ratios of the device 
and available fonts. 


Return Value 


The return value specifies the previous value of the font-mapper flag. 


Comments 


The remaining bits of the wFlag parameter must be zero. 


BOOL SetMenu(hWnd, hMenu) 


This function sets the given window’s menu to the menu specified by the 
hMenu parameter. If hMenu is NULL, the window’s current menu is 
removed. The SetMenu function causes the window to be redrawn to 
reflect the menu change. 


Parameter Type/Description 

hWnd HWND sIdentifies the window whose menu is to be 
changed. 

hMenu HMENU Identifies the new menu. 


Return Value 


The return value specifies whether the menu is changed. It is nonzero if the 
menu is changed. Otherwise, it is zero. 
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Comments 


SetMenu will not destroy a previous menu. An application should call the 
Destroy Menu function to accomplish this task. | 


BOOL SetMessageQueue(cMsqg) 


This function creates a new message queue. It is particularly useful in 
applications that require a queue that contains more than eight messages 
(the maximum size of the default queue). The cMsg parameter specifies 
the size of the new queue; the function must be called from an applica- 
tion’s WinMain function before any windows are created. The 

Set MessageQueue function destroys the old queue, along with messages 
it might contain. 


Parameter Type/Description 


cMsg int Specifies the maximum number of messages that 
the new queue may contain. 


Return Value 


The return value specifies whether a new message queue is created. It is 
nonzero if the function creates a new queue. Otherwise, it is zero. 


Comments 


If the return value is zero, the application has no queue because the 
SetMessageQueue function deletes the original queue before attempt- 
ing to create a new one. The application must continue calling Set- 
MessageQueue with a smaller queue size until the function returns 

a nonzero value. 


HANDLE SetMetaFileBits(hMem) 


This function creates a memory metafile from the data in the global 
memory block specified by the hMem parameter. 


Parameter Type/ Description 


hMem HANDLE Identifies the global memory block that 
contains the metafile data. It is assumed that the data 
were previously created by using the GetMetaF ileBits 
function. 


434 


SetPixel 


Return Value 


The return value identifies a memory metafile if the function is successful. 
Otherwise, the return value is NULL. 


Comments 


After the SetMetaFileBits function returns, AMF, the metafile handle, 
should be used instead of hMem to refer to the metafile. 


HWND SetParent(hWndChild, hWndNewParent) 
This function changes the parent window of a child window. If the window 


identified by the hWndChild parameter is visible, Windows performs the 
appropriate redrawing and repainting. 


Parameter Type/Description 


hWndChild HWND Identifies the child window. 
hWndNewParent HWND Identifies the new parent window. 


Return Value 


The return value identifies the previous parent window. 


DWORD SetPixel(hDC, X, Y, rgbColor) 


This function sets the pixel at the point specified by the X and Y parame- 
ters to the closest approximation of the color specified by the rgbColor 
parameter. The point must be in the clipping region. If the point is not in 
the clipping region, the function is ignored. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

X short Specifies the logical zcoordinate of the point to 
be set. 

Y short Specifies the logical ycoordinate of the point to 
be set. 

rgbColor DWORD Specifies an RGB color value of the color 


used to paint the point. 


435 


SetPixel 


Return Value 


The return value specifies an RGB color value for the color that the point 
is actually painted. This value can be different than that specified by the 
rgoColor parameter if an approximation of that color is used. If the func- 
tion fails—for example, if the point is outside the clipping region—the 
return value is —1. 


Comments 


Not all devices support the SetPixel function. For more information, see 
the RC.. BITBLT capability in the GetDeviceCaps function, earlier in 
this chapter. 


short SetPolyFillMode(hDC, nPolyFillMode) 


This function sets the polygon-filling mode for the GDI functions that use 
the polygon algorithm to compute interior points. 


Parameter Type/ Description 


hDC HDC Identifies the device context. 


nPolyFillMode short Specifies the new filling mode. The nPoly- 
FillMode parameter may be either of the following 


values: 

Value Meaning 

ALTERNATE Selects alternate mode. 
WINDING Selects winding number mode. 


Return Value 


The return value specifies the previous filling mode. It 1s zero if there is an 
error. 


Comments 


In general, the modes differ only in cases where a complex, overlapping 
polygon must be filled (for example, a five-sided polygon that forms a five- 
pointed star with a pentagon in the center). In such cases, ALTERNATE 
mode fills every other enclosed region within the polygon (that is, the 
points of the star), but WINDING mode fills all regions (that is, the points 
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and the pentagon). To fill all regions, WINDING mode causes GDI to com- 
pute and draw a border that encloses the polygon but does not overlap. 
For example, in WINDING mode, the five-sided polygon that forms the 
star is drawn as a ten-sided polygon with no overlapping sides; the result- 
ing star 1s filled. 


int SetPriority(h Task, nChangeAmount) 


This function modifies the task priority of the task specified by the hTask 
parameter by adding the amount specified in the nChangeAmount parame- 
ter to the current priority. ‘The task priority can be modified to any value 
in the range -15 to 15. The highest task priority is —15, the lowest is 15. 
Task priority is initially set to zero. 


Parameter Type/Description 
hTask HANDLE Identifies the task to be set. 
nChangeAmount int Specifies the amount to change the priority. 


Return Value 


The return value specifies the new priority of the task. 


Comments 


The hTask parameter is obtained by calling the GetCurrentTask 
function. 


BOOL SetProp(hWnd, lpString, hData) 


This function adds a new entry or changes an existing entry in the prop- 
erty list of the specified window. The SetProp function adds a new entry 
to the lst if the character string specified by the [pString parameter does 
not already exist in the list. The new entry contains the string and the 
handle. Otherwise, the function replaces the string’s current handle with 
the one specified by the hData parameter. 


Although hData can be a handle to any type of data, the application must 
ensure that the handle is valid. 
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Parameter Type/Description 


hWnd HWND Identifies the window whose property list is to 
receive the new entry. 


lnString LPSTR. Points to a null-terminated character string 
or an atom that identifies a string. If an atom 1s given, 
it must have been previously created by using the 
AddAtom function. The atom, a 16-bit value, must be 
placed in the low-order word of IpString; the high-order 
word must be zero. 


hData HANDLE Identifies a data handle to be copied to the 
property list. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
data handle and string are added to the property list. Otherwise, it is zero. 


Comments 


The application is responsible for removing all entries from the property 
list. before destroying the window (that is, before the application processes 
the WM_ DESTROY message). The RemoveProp function must be used 
to remove entries from a property list. 


void SetRect(/pRect, X1, Y1, X2, Y?) 


This function creates a new rectangle by filling the RECT data structure 
pointed to by the IpRect parameter with the coordinates given by the X1, 
Y1, X2, and Y2 parameters. 


Parameter Type/Description 

lnRect LPRECT Points to the RECT data structure that is 
to receive the new rectangle coordinates. 

X1 int Specifies the zcoordinate of the upper-left corner. 

Y1 int Specifies the ycoordinate of the upper-left corner. 

X2 int Specifies the scoordinate of the lower-right corner. 

Y2 int Specifies the ycoordinate of the lower-right corner. 
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Return Value 


None 


Comments 
The width of the rectangle, specified by the absolute value of X2 — X17, 


must not exceed 32,767 units. This limit applies to the height of the 
rectangle as well. 


void SetRectEmpty(lpRect) 


This function creates an empty rectangle (all coordinates equal to zero). 


Parameter Type/ Description 


lpRect LPRECT Points to the RECT data structure that is 
to receive the empty rectangle. 


Return Value 


None 


void SetRectRgn(hRgn, X1, Y1, X2, Y2) 


This function creates a rectangular region. Unlike CreateRectRegion, 
however, it does not call the local memory manager; instead, it uses the 
space allocated for the region associated with the hRgn parameter. The 
points given by the X7, Y1, X2, and Y2 parameters specify the minimum 
size of the allocated space. 


Parameter Type/Description 
hRgn HANDLE Identifies the region. 
XI short Specifies the coordinate of the upper-left 


corner of the rectangular region. 


Y1 short Specifies the ycoordinate of the upper-left 
corner of the rectangular region. 


X2 short Specifies the zcoordinate of the lower-right 
corner of the rectangular region. 


Y2 short Specifies the ycoordinate of the lower-right 
corner of the rectangular region. 
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Return Value 


None 


Comments 


Use this function instead of the CreateRectRgn function to avoid calls 
to the local memory manager. 


short SetRelAbs(hDO, nRelAbsMode) 


This function sets the relative or absolute mode. This function specifies 
whether the coordinates in GDI functions are relative to the origin of the 
given device (absolute), or relative to the current position (relative). 


Parameter Type/Description 


hDC HDC Identifies the device context. 


nRelAbsMode short Specifies the new mode. It can be either of the 
following values: 


Value Meaning 

ABSOLUTE = Sets mode to absolute. 

RELATIVE Sets mode to relative. 
Return Value 


The return value specifies the previous setting of the relative or absolute 
mode. It can be ABSOLUTE or RELATIVE. It is NULL if the ADC param- 
eter is not a valid display context. 


Comments 


The nfelAbsMode parameter affects the output created by the LineTo 
and Polyline functions. 


FARPROC SetResourceHandler(hinstance, lp Type, lpLoadFunc) 


This function sets up a function to load resources. It is used internally by 
Windows to implement calculated resources. Applications may find this 
function useful for handling their own resource types, but its use is not 
required. 
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The [pLoadFunc parameter points to an application-supplied callback 
function. The function pointed to by the lpLoadF unc parameter receives 
information about the resource to be locked and can process that informa- 
tion as desired. After the function pointed to by lpLoadF unc returns, 
LockResource attempts to lock the resource once more. 


Parameter Type/Description 


hInstance HANDLE Identifies the instance of the module whose 


executable file contains the resource. 


lp Type LPSTR Points to a short integer that specifies a 
resource type. 


lnLoadFunc FARPROC Is the procedure-instance address of the 
application-supplied callback function. See the following 
“Comments” section for details. 


Return Value 


The return value points to the application-supplied function. 


Comments 


The callback function must use the Pascal calling convention and must be 
declared FAR. The function must have the following form: 


FARPROC FAR PASCAL LoadFunc(Mem, hinstance, hResInfo) 
HANDLE hMem; 

HANDLE hinstance; 

HANDLE AResInfo; 


LoadF unc is a placeholder for the application-supplied function name. The 
actual name must be exported by including it in an EXPORTS state- 
ment in the application’s module-definition file. 


Parameter Description 

hMem Identifies a stored resource. 

hinstance Identifies the instance of the module whose executable 
file contains the resource. 

hResInfo Identifies the resource. It is assumed that the resource 
was created previously by using the FindResource 
function. 
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Comments 


The hMem parameter is NULL if the resource has not yet been loaded. If 
an attempt to lock a block specified by hMem fails, this means the resource 
has been discarded and must be reloaded. 


short SetROP2(hDC, nDrawMode) 


This function sets the current drawing mode. GDI uses the drawing mode 
to combine pens and interiors of filled objects with the colors already on 
the display surface. The mode specifies how the color of the pen or interior 
and the color already on the display surface yield a new color. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
nDrawMode short Specifies the new drawing mode. It can be any 


one of the values given in Table 3.17. 


Return Value 


The return value specifies the previous drawing mode. It can be any one of 
the values given in Appendix A, “Binary and Ternary Raster-Operation 
Codes and Definitions.” 


Comments 


Drawing modes define how GDI combines source and destination colors 
when drawing with the current pen. The drawing modes are actually 
binary raster-operation codes, representing all possible Boolean functions 
of two variables, using the binary operations AND, OR, and XOR 
(exclusive OR), and the unary operation NOT. The drawing mode is for 
raster devices only; it is not available on vector devices. For more informa- 
tion, see the RC_BITBLT capability in the GetDeviceCaps function, 
earlier in this chapter. Table 3.17 shows the drawing modes for the 
nDrawMode parameter: 
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Table 3.17 
Drawing Modes 


Value 


R2_ BLACK 
R2. NOTMERGEPEN 
R2_ MASKNOTPEN 


R2_ NOTCOPYPEN 
R2_ MASKPENNOT 


R2_ NOT 
R2_ XORPEN 


R2_ NOTMASKPEN 
R2_ MASKPEN 


R2_ NOTXORPEN 
R2_ NOP 
R2_ MERGENOTPEN 


R2_. COPYPEN 
R2_ MERGEPENNOT 


R2_ MERGEPEN 


R2_ WHITE 


SetROP2 


Meaning 


Pixel is always black. 
Pixel is the inverse of the R2- MERGEPEN color. 


Pixel is a combination of the colors common to both 
the display and the inverse of the pen. 


Pixel is the inverse of the pen color. 


Pixel is a combination of the colors common to both 
the pen and the inverse of the display. 


Pixel is the inverse of the display color. 


Pixel is a combination of the colors in the pen and in 
the display, but not in both. 


Pixel is the inverse of the R2_- MASKPEN color. 


Pixel is a combination of the colors common to both 
the pen and the display. 


Pixel is the inverse of the R2_ XORPEN color. 
Pixel remains unchanged. 


Pixel is a combination of the display color and the 
inverse of the pen color. 


Pixel is the pen color. 


Pixel is a combination of the pen color and the 
inverse of the display color. 


ae is combination of the pen color and the display 
color. 


Pixel is always white. 


For more information about the drawing modes, see Appendix A, “Binary 
and Ternary Raster-Operation Codes and Definitions.” 
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int SetScrollPos(hWnd, nBar, nPos, bRedraw) 
This function sets the current position of a scroll-bar thumb to that spec- 


ified by the nPos parameter and, if specified, redraws the scroll bar to 
reflect the new position. 


Parameter Type/Description 


hWnd HWND ldentifies the window whose scroll bar is to be 
set. 
nBar int Specifies the scroll bar to be set. It can be one of 


the following values: 
Value Meaning 


SB. CTL Sets the position of a scroll-bar 
control. In this case, the hWnd 
parameter must be the handle 
of a scroll-bar control. 


SB. HORZ Sets a window’s horizontal scroll-bar 
position. 
SB. VERT Sets a window’s vertical scroll-bar 
position. 
nPos int Specifies the new position. It must be within the 
scrolling range. 
bRedraw BOOL Specifies whether the scroll bar should be 


redrawn to reflect the new position. If the bRedraw 
parameter is nonzero, the scroll bar is redrawn. If it 
is zero, it is not redrawn. 


Return Value 
The return value specifies the previous position of the scroll-bar thumb. 
Comments 


Setting the bRedraw parameter to zero is useful whenever the scroll bar 
will be redrawn by a subsequent call to another function. 
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void SetScrollRange(hWnd, nBar, nMinPos, nMaxPos, bRedraw) 


This function sets minimum and maximum position values for the given 
scroll bar. It can also be used to hide or show standard scroll bars. 


Parameter Type/Description 


hWnd HWND Identifies a window or a scroll-bar control, 
depending on the value of the nBar parameter. 


nBar int Specifies the scroll bar to be set. It can be one of 
the following values: 


Value Meaning 


SB. CTL Sets the range of a scroll-bar 
control. In this case, the hWnd 
parameter must be the handle 
of a scroll-bar control. 


SB. HORZ Sets a window’s horizontal scroll-bar 
range. 
SB. VERT Sets a window’s vertical scroll-bar 
range. 
nMinPos int Specifies the minimum scrolling position. 
nMazPos int Specifies the maximum scrolling position. 
bRedraw BOOL Specifies whether or not the scroll bar should 


be redrawn to reflect the change. If the bRedraw parame- 
ter is nonzero, the scroll bar is redrawn. If it is zero, it is 
not redrawn. 


Return Value 


None 


Comments 


A scroll-bar control cannot be hidden by making the minimum and max- 
imum scroll-range positions equal. Although this technique can be applied 
to a scroll-bar control, it disables the control but does not hide it. Only 
standard scroll bars, accessed by means of the SB_HORZ or SBL VERT 
values, can be hidden in this way. When a scroll bar is hidden, the window 
is always updated to reflect the change, regardless of the value of the 
bRedraw parameter. A scroll-bar control cannot be hidden. 
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The SetScrollRange function restores a hidden scroll bar if the minimum 


and maximum values are not equal. 


If SetScrollRange immediately follows the SetScrollPos function, the 


bRedraw parameter in SetScrollPos should be set to zero to prevent the 


scroll bar from being drawn twice. 


int SetSoundNoise(nSource, nDuration) 


io Sy 


This function sets the source and duration of a noise in the noise hardware 


of the play device. 
Parameter Type/ Description 


nSource 


int Specifies the noise source. It can be any one of the 


following values, where N is a value used to derive a tar- 


get frequency: 
Value 
S.. PERIOD512 


S— PERIOD1024 
S. PERIOD2048 


S. PERIODVOICE 
S— WHITES12 


S— WHITE1024 
S— WHITE2048 


S_ WHITEVOICE 


nDuration 


Return Value 


Meaning 

Source frequency is N/512 
(high pitch); hiss is less coarse. 
Source frequency is N/1024. 


Source frequency is N/2048 
(low pitch); hiss is coarser. 


Source frequency from voice 
channel 3. 


Source frequency is N/512 
(high pitch); hiss is less coarse. 


Source frequency is N/1024. 


Source frequency is N/2048 
(low pitch); hiss is coarser. 


Source frequency from voice 
channel 3. 


int Specifies the duration of the noise (in clock ticks). 


The return value specifies the result of the function. It is zero if the func- 
tion is successful. If the source is invalid, the return value is S-SERDSR. 


446 


SetStretchBltMode 


short SetStretchBltMode(hDC, nStretchMode) 


This function sets the stretching mode for the StretchBlt function. The 
stretching mode defines which scan lines and/or columns StretchBIt 
eliminates when contracting a bitmap. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


nStretchMode short Specifies the new stretching mode. It can be one 
of the following values: 


Value Meaning 


BLACKONWHITE — AND in the eliminated lines. This 
mode preserves black pixels at the 
expense of white pixels by using 
the AND operator on the elim- 
inated lines and those remaining. 


COLORONCOLOR _ Deletes the elzminated lines. This 
mode deletes all eliminated lines 
without trying to preserve their 
information. 


WHITEONBLACK — OR in the elsminated lines. This 
mode preserves white pixels at the 
expense of black pixels by using 
the OR operator on the lines to 
re eliminated and the remaining 
ines. 


The BLACKONWHITE and 
WHI'TEONBLACK modes are 
typically used to preserve fore- 
ground pixels in monochrome bit- 
maps. The COLORONCOLOR 
mode is typically used to preserve 
color in color bitmaps. 


Return Value 


The return value specifies the previous stretching mode. It can be 


BLACKONWHITE, COLORONCOLOR, or WHITEONBLACK. 
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int SetSwapAreaSize(rsSize) 


This function increases the amount of memory that an application uses for 
its code segment. The maximum amount of memory available is one-half 
of the space remaining after Windows is loaded. 


Parameter Type/Description 


rsSize WORD Specifies the number of paragraphs requested 
by the application for use as a code segment. 


Return Value 


The return value specifies the number of paragraphs obtained for use as a 
code segment. 


Comments 


Once memory has been dedicated for use as code segment, an application 
cannot use it as a data segment by calling the GlobalAlloc function. 


void SetSysColors(nChanges, lpSysColor, lp Color Values) 


This function sets the system colors for one or more display elements. 
Display elements are the various parts of a window and the Windows 
display that appear on the system display screen. The SetSysColors func- 
tion changes the number of elements specified by the nChanges parameter, 
using the color and system-color index contained in the arrays pointed to 
by the lpSysColor and lpColor Values parameters. 


SetSysColors sends a WM_SYSCOLORCHANGE message to all win- 
dows to inform them of the change in color. It also directs Windows to 
repaint the affected portions of all currently visible windows. 


Parameter Type/Description 

nChanges int Specifies the number of system colors to be 
changed. 

lpSysColor LPINT Points to an array of integer indexes that 


specify the elements to be changed. The index values 
that can be used are listed in Table 3.18. 


lnColorValues long FAR * Points to an array of unsigned long 
integers that contains the new RGB color values for 
each element. 
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Return Value 


None 


Comments 


SetSysColors 


SetSysColors changes the internal system list only. It does not change © 


the [colors] section of the Windows initialization file, win.int. Changes 
apply to the current Windows session only. System colors are a shared 


resource. An application should not change a color if 1t does not wish to 
change colors for all windows in all currently running applications. System 
colors for monochrome displays are usually interpreted as various shades 
of gray. ‘T'able 3.18 lists the values for the lpSysColor parameter: 


Table 3.18 


System Color Indexes 


Value 


COLOR ACTIVEBORDER 
COLOR_ ACTIVECAPTION 
COLOR_ APPWORKSPACE 


COLOR_ BACKGROUND 
COLOR_ CAPTIONTEXT 


COLOR_. INACTIVEBORDER 
COLOR_ INACTIVECAPTION 
COLOR_ MENU 

COLOR. MENUTEXT 
COLOR_ SCROLLBAR 
COLOR WINDOW 


COLOR_. WINDOWFRAME 


COLOR_ WINDOWTEXT 


Meaning 


Active window border 
Active window caption 


Background color of multiple 
document interface (MDI) 
applications 


Desktop 


Text in caption, size box, 
scroll-bar arrow box 


Inactive window border 
Inactive window caption 
Menu background 

Text in menus 
Scroll-bar gray area 


Window background and 
thumb box 


Window border, caption text 
background 


Text in windows 
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HWND SetSysModalWindow(hWnd) 


This function makes the specified window a system-modal window. 


Parameter Type/Description 
hWnd HWND Identifies the window to be made system 
modal. 


Return Value 


The return value identifies the window that was previously the system- 
modal window. 


Comments 


If another window is made the active window (for example, the system- 
modal window creates a dialog box that becomes the active window), the 
active window becomes the system-modal window. When the original win- 
dow becomes active again, it is system modal. To end the system-modal 
state, destroy the system-moda] window. 


WORD SetTextAlign(hDC, wFlags) 


This function sets the text-alignment flag for the given device context. The 
TextOut function uses this flag when it positions a string of text on a 
display or device. The flag specifies the relationship between a specific 
point and a rectangle that bounds the text. The coordinates of this point 
are passed as parameters to the TextOut function. The rectangle that 
bounds the text is formed by the adjacent character cells in the text 
string. 


Parameter Type/Description 

ADC HDC Identifies the device or display selected for text 
output. 

wk lags WORD Specifies a mask of the values in the following 


list. Only one flag may be chosen from those that affect 
horizontal and vertical alignment. In addition, only one 
of the two flags that alter the current position can be 
chosen: 


450 


_ Ta OP 
IA _ CEE “Ta BIGHF 
oedh: 2 er Me Sle i, avast a 8 a EGE 
TA CENTER | aA Dey + ee 
TA BATE LIE De 
iy sa 
ne) a 
TA_BOTTOM 


Return Value 


Value 
TA_ BASELINE 


TA. BOTTOM 


TA. CENTER 


TAY LEFT 


Set TextAlign 


Meaning 


Specifies alignment of the point and 
the baseline of the chosen font at 
the left side of the bounding rect- 
angle. 


Specifies alignment of the point and 
the bottom center of the bounding 
rectangle. 


Specifies alignment of the point 
and the center of the bounding 
rectangle’s left side. 


Specifies alignment of the point and 
the upper-left corner of the bound- 
ing rectangle. 


TA NOUPDATECP 


TA RIGHT 


TA~ TOP 


TA UPDATECP 


Specifies that the current position is 
not updated after each TextOut 
function call. 


Specifies alignment of the point and 
the upper-right corner of the bound- 
ing rectangle. 


Specifies alignment of the point 
and the top center of the bounding 
rectangle. 


Specifies that the current position is 
updated after each TextOut func- 
tion call. 


The return value specifies the alignment: the low-order word contains 
the horizontal alignment, and the high-order word contains the vertical 


alignment. 
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short SetTextCharacterExtra(hDC, nCharExztra) 


This function sets the amount intercharacter of spacing. GDI adds this _ 
spacing to each character, including break characters, when it writes a line 
of text to the display surface. 


Parameter Type/ Description 
hDC HDC Identifies the device context. 
nCharExtra short Specifies the amount of extra space (in logical 


units) to be added to each character. If the current map- 
ping mode is not MM_ TEXT, the nCharExztra parameter 
is transformed and rounded to the nearest pixel. 


Return Value 


The return value specifies the amount of the previous intercharacter 
spacing. 


DWORD SetTextColor(hDC, rgbColor) 


This function sets the text color to the color specified by the rgbColor 
parameter, or to the nearest logical color if the device cannot represent the 
color specified by rgbColor. GDI uses the text color to draw the face of 
each character written by the TextOut function. GDI also uses the text 
color when converting bitmaps from color to monochrome and vice versa. 


The background color for a character is specified by the SetBkColor and 


SetBkMode functions. For color-bitmap conversions, see the BitBlt and 
StretchBlit functions, earlier in this chapter. 


Parameter Type/ Description 


hDC HDC Identifies the device context. 
rgbColor DWORD Specifies an RGB color value for the color of 
the text. 


Return Value 


The return value specifies an RGB color value for the previous text color. 
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short SetTextJustification(hDO, nBreakExtra, nBreakCount) 


This function prepares GDI to justify a line of text using the justification 
parameters specified by the nBreakEztra and nBreakCount parameters. To 
justify text, GDI distributes extra pixels among break characters in a text 
line written by the TextOut function. The break character, used to de- 
limit words, is usually the space character (ASCII 32), but may be defined 
by a font as some other character. The Get TextMetrics function can be 
used to retrieve a font’s break character. 


The Set TextJustification function prepares the justification by defining 
the amount of space to be added. The nBreakE xtra parameter specifies 
the total amount of space (in logical units) to be added to the line. The 
nBreakCount parameter specifies how many break characters are in the 
line. The subsequent TextOut function distributes the extra space evenly 
between each break character in the line. 


Get TextExtent is always used with the Set Text Justification func- 
tion. The Get TextExtent function computes the width of a given line 
before justification. This width must be known before an appropriate 
nBreakExtra value can be computed. 


Set TextJustification can be used to justify a line that contains multiple 
runs in different fonts. In this case, the line must be created piecemeal by 
justifying and writing each run separately. 


Because rounding errors can occur during justification, GDI keeps a run- 
ning error term that defines the current error. When justifying a line that 
contains multiple runs, Get TextExtent automatically uses this error 
term when it computes the extent of the next run, allowing TextOut to 
blend the error into the new run. After each line has been justified, this 
error term must be cleared to prevent it from being incorporated into the 
next line. The term can be cleared by calling Set Text Justification with 
nBreakExtra set to zero. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
nBreakExtra short Specifies the total extra space (in logical units) 


to be added to the line of text. If the current mapping 
mode is not MM... TEXT, nBreakEsztra is transformed 


and rounded to the nearest pixel. 


nBreakCount short Specifies the number of break characters in the 
line. 
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Return Value 


The return value specifies the outcome of the function. It is 1 if the func- 
tion is successful. Otherwise, it is zero. 


WORD Set Timer(hWnd, nIDEvent, wElapse, lp TimerFunc) 


This function creates a system timer event identified by the nIDEvent 
parameter. When a timer event occurs, Windows passes a WM_ TIMER 
message to the application-supplied function specified by the lp TimerF'unc 
parameter. The function can then process the event. A NULL value for 

ln TimerFunc causes WM_ TIMER messages to be placed in the application 
queue. 


Parameter Type/Description 


hWnd HWND Identifies the window to be associated with 
the timer. If hWnd is NULL, no window is associated 
with the timer. 


nlDEvent short Specifies the timer-event identifier if the hWnd 
parameter is not NULL. If the hWnd parameter is 
NULL, the nJDEvent parameter is ignored and the 
SetTimer function returns its own unique identifier 
for the event. 


whlapse unsigned Specifies the elapsed time (in milli- 
seconds) between timer events. 


lo TomerF'unc FARPROC Is the procedure-instance address of the 
function to be notified when the timer event takes place. 
If lp TimerFunc is NULL, the WM_ TIMER message is 
placed in the application queue; the hWnd member of 
the MSG structure contains the hWnd parameter given 
in the Set Timer function call. See the following “Com- 
ments” section for details. 


Return Value 
The return value specifies the integer identifier for the new timer event if 


the hWnd parameter is NULL. The return value is nonzero if the timer was 
created. Otherwise, it is zero. 
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Comments 


Timers are a limited global resource; therefore, it is important that an 
application check the value returned by the Set Timer function to verify 
that a timer is actually available. 


To install a timer function, Set Timer must receive a procedure-instance 
address of the function, and the function must be exported in the appli- 
cation’s module-definition file. A procedure-instance address can be 
created using the MakeProcInstance function. 


The callback function must use the Pascal calling convention and must be 
declared FAR. The callback function must have the following form: 


WORD FAR PASCAL TimerFunc(hWnd, wMsg, nIDEvent, dwTime) 
HWND hWnd; 

WORD wMszg; 

int nlDEvent; 

DWORD dwTime; 


TumerF unc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Description 

hWnd Identifies the window associated with the timer event. 
wMsg Specifies the WM_ TIMER message. 

nlDEvent Specifies the timer’s ID. 

dwTime Specifies the current system time. 


DWORD SetViewportExt(hDC, X, Y) 


This function sets the and yextents of the viewport of the specified 
device context. The viewport, along with the device-context window, 
defines how GDI maps points in the logical coordinate system to points in 
the coordinate system of the actual device. In other words, they define how 
GDI converts logical coordinates into device coordinates. 


The z- and y-extents of the viewport define how much GDI must stretch or 
compress units in the logical coordinate system to fit units in the device 
coordinate system. For example, if the z-extent of the window is 2 and the 
z-extent of the viewport is 4, GDI maps two logical units (measured from 
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the z-axis) into four device units. Similarly, if the y-extent of the window 
is 2 and the y-extent of the viewport is —1, GDI maps two logical units 
(measured from the y-axis) into one device unit. 


The extents also define the relative orientation of the z- and y-axes in both 
coordinate systems. If the signs of matching window and viewport extents 
are the same, the axes have the same orientation. If the signs are different, 
the orientation is reversed. For example, if the y-extent of the window is 9 
and the y-extent of the viewport 1s —1, GDI maps the positive y-axis in the 
logical coordinate system to the negative y-axis in the device coordinate 
system. If the z-extents are 2 and 4, GDI maps the positive a-axis in the 
logical coordinate system to the positive z-axis in the device-coordinate 
system. 


Parameter Type/Description 


ADC HDC Identifies the device context. 

xX short Specifies the z-extent of the viewport (in device 
units). 

Y eer Specifies the y-extent of the viewport (in device 
units}, 


Return Value 


The return value specifies the previous extents of the viewport. The pre- 
vious y-extent is in the high-order word; the previous z-extent is in the 
low-order word. When an error occurs, the return value is zero. 


Comments 


When the following mapping modes are set, calls to the Set WindowExt 
and Set ViewportExt functions are ignored: 


MMW HIENGLISH 
MM_ HIMETRIC 
MM_ LOENGLISH 
MM. LOMETRIC 
MM_ TEXT 

MMW. ‘TWIPS 


When MM_ISOTROPIC mode is set, an application must call the 
Set WindowExt function before it calls Set ViewportExt. 


456 


Set VoiceAccent 


DWORD SetViewportOrg(hDC, X, Y) 


This function sets the viewport origin of the specified device context. The 
viewport, along with the device-context window, defines how GDI maps 
points in the logical coordinate system to points in the coordinate system 
of the actual device. In other words, they define how GDI converts logical 
coordinates into device coordinates. 


The viewport origin marks the point in the device coordinate system to 
which GDI maps the window origin, a point in the logical coordinate sys- 
tem specified by the Set WindowOrg function. GDI maps all other points 
by following the same process required to map the window origin to the 
viewport origin. For example, all points in a circle around the point at the 
window origin will be in a circle around the point at the viewport origin. 
Similarly, all points in a line that passes through the window origin will be 
in a line that passes through the viewport origin. 


Parameter Type/Description 
ADC HDC Identifies the device context. 
xX short Specifies the z-coordinate (in device units) of the 


origin of the viewport. The value must be within the 
range of the device coordinate system. 


Y short Specifies the y-coordinate (in device units) of 
the origin of the viewport. The value must be within the 
range of the device coordinate system. 


Return Value 


The return value specifies the previous origin of the viewport (in device 
coordinates). The y-coordinate is in the high-order word; the z-coordinate 
is in the low-order word. 


int SetVoiceAccent(nVoice, nTempo, nVolume, nMode, nPitch) 


This function places an accent (tempo, volume, mode, and pitch) in the 
voice queue specified by the n Voice parameter. "The new accent replaces 
the previous accent and remains in effect until another accent is queued. 
An accent is not counted as a note. 


An error occurs if there is insufficient room in the queue; the 

Set VoiceAccent function always leaves space for a single sync mark 
in the queue. If nVozce is out of range, the Set VoiceAccent function 
is ignored. 
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Parameter Type/ Description 

nVoice int Specifies a voice queue. The first voice queue is 
numbered I. 

nTempo int Specifies the number of quarter notes played per 
minute. It can be any value from 32 to 255. The default 
is 120. 

nVolume int Specifies the volume level. [t can be any value from 
0 (lowest volume) to 255 (highest). 

nMode int Specifies how the notes are to be played. It can be 
any one of the following values: 
Value Meaning 
S_ LEGATO Note is held for the full duration 


and blended with the beginning of 
the next note. 


S. NORMAL Note is held for the full duration, 
coming to a full stop before the 
next note starts. 


S_ STACCATO Note is held for only part of the 
duration, creating a pronounced 
stop between it and the next note. 


nPitch int Specifies the pitch of the notes to be played. It can 
be any value from 0 to 83. The pitch value is added to 
the note value, using modulo 84 arithmetic. 


Return Value 


The return value specifies the result of the function. It is zero if the func- 
tion is successful. If an error occurs, the return value is one of the follow- 
ing values: 


S.. SERDMD Invalid mode 
S.. SERDTP Invalid tempo 
S..SERDVL Invalid volume 
S— SERQFUL Queue full 
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int Set VoiceEnvelope(n Voice, nShape, nRepeat) 


This function queues the envelope (wave shape and repeat count) in the 
voice queue specified by the nVoice parameter. The new envelope replaces 
the previous one and remains in effect until the next Set VoiceEnvelope 
function call. An envelope is not counted as a note. 


An error occurs if there is insufficient room in the queue; the Set Voice- 
Envelope function always leaves space for a single sync mark in the 
queue. If nVorce is out of range, Set VoiceEnvelope is ignored. 


Parameter Type/Description 

nVoice int Specifies the voice queue to receive the envelope. 
nShape int Specifies an index to an OEM wave-shape table. 
nRepeat int Specifies the number of repetitions of the wave 


shape during the duration of one note. 


Return Value 


The return value specifies the result of the function. It is zero if the func- 
tion is successful. If an error occurs, the return value is one of the follow- 
ing values: 


S_ SERDRC Invalid repeat count 
S_SERDSH Invalid shape 
S_ SERQFUL Queue full 


int Set VoiceNote(n Voice, nValue, nLength, nCdots) 


This function queues a note that has the qualities given by the nValue, 
nLength, and nCdots parameters in the voice queue specified by the nVoice 
parameter. An error occurs if there is insufficient room in the queue. The 
function always leaves space in the queue for a single sync mark. 


Parameter Type/Description 

nVoice int Specifies the voice queue to receive the note. If 
nVoice is out of range, the Set VoiceNote function is 
ignored. 

nValue int Specifies 1 of 84 possible notes (seven octaves). If 


nValue is zero, a rest is assumed. 
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nLength int Specifies the reciprocal of the duration of the note. 
For example, 1 specifies a whole note, 2 a half note, 4a 
quarter note, and so on. 


nCdots int Specifies the duration of the note in dots. The 
duration is equal to nLength X (nCdots X 3/2). a 


Return Value 


The return value specifies the result of the function. It is zero if the func- 
tion is successful. If an error occurs, the return value is one of the follow- 
ing values: 


S.SERDCC Invalid dot count 
S_SERDLN Invalid note length 
Ss. SERDNT Invalid note 
S~SERQFUL Queue full 


int Set VoiceQueueSize(n Voice, nBytes) 


This function allocates the number of bytes specified by the nBytes param- 
eter for the voice queue specified by the nVoice parameter. If the queue 
size is not set, the default is 192 bytes, which is room for about 32 notes. 
All voice queues are locked in memory. The queues cannot be set while 
music is playing. 


Parameter Type/ Description 
nVotce int Specifies a voice queue. 
nBytes int Specifies the number of bytes in the voice queue. 


Return Value 


The return value specifies the result of the function. It 1s zero if the func- 
tion is successful. If an error occurs, the return value is one of the follow- 
ing values: 


S_ SERMACT Music active 
S. SEROFM Out of memory 
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int SetVoiceSound(nVoice, Frequency, nDuration) 


This function queues the sound frequency and duration in the voice queue 
specified by the nVorce parameter. 


Parameter Type/ Description 

n Voice int Specifies a voice queue. The first voice queue is 
numbered 1. 

AF requency inf Specifies the frequency. The high-order word con- 


tains the frequency in kilohertz, and the low-order word 
contains the fractional frequency. 


nDuration int Specifies the duration of the sound (in clock ticks). 


Return Value 


The return value specifies the result of the function. It is zero if the func- 
tion is successful. If an error occurs, the return value is one of the follow- 
ing values: 


S_ SERDDR Invalid duration 
S_SERDFOQ Invalid frequency 
S_ SERDVL Invalid volume 
S_SERQFUL Queue full 


int Set VoiceThreshold(nVozce, nNotes) 


This function sets the threshold level for the given voice. When the 

number of notes remaining in the voice queue goes below that specified in 

the nNotes parameter, the threshold flag is set. If the queue level is below 
that specified in nNotes when the Set VoiceThreshold function is called, | 
the flag is not set. The Get ThresholdStatus function should be called to 
verify the current threshold status. 


Parameter Type/Description 


nVotce int Specifies the voice queue to be set. 
nNotes int Specifies the number of notes in the threshold 
level. 
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Return Value 


The return value specifies the result of the function. It is zero if the func- 
tion is successful. It is 1 if the number of notes specified in nNotes is out of 
range. 


DWORD SetWindowExt(hDC, X, Y) 


This function sets the z- and y-extents of the window associated with the . 
specified device context. The window, along with the device-context 
viewport, defines how GDI maps points in the logical coordinate system 

to points in the device coordinate system. 


The z- and y-extents of the window define how much GDI must stretch or 
compress units in the logical coordinate system to fit units in the device 
coordinate system. For example, if the z-extent of the window is 2 and the 
z-extent of the viewport is 4, GDI maps two logical units (measured from 
the z-axis) into four device units. Similarly, if the y-extent of the window 
is 2 and the y-extent of the viewport is —1, GDI maps two logical units 
(measured from the y-axis) into one device unit. 


The extents also define the relative orientation of the z- and y-axes in both 
coordinate systems. If the signs of matching window and viewport extents 
are the same, the axes have the same orientation. If the signs are different, 
the orientation is reversed. or example, if the y-extent of the window is 2 
and the y-extent of the viewport is -1, GDI maps the positive y-axis in the 
logical coordinate system to the negative y-axis in the device coordinate 
system. If the z-extents are 2 and 4, GDI maps the positive z-axis in the 
logical coordinate system to the positive z-axis in the device coordinate 
system. 


Parameter Type/ Description 
— ADC HDC | Identifies the device context. 
xX short Specifies the z-extent (in logical units) of the 
window. 
Y short Specifies the y-extent (in logical units) of the 
window. 


Return Value 
The return value specifies the previous extents of the window (in logical 


units). The y-extent is in the high-order word; the z-extent is in the low- 
order word. If an error occurs, the return value is zero. 
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Comments 


When the following mapping modes are set, calls to the Set WindowExt 
and Set ViewportExt functions are ignored: 


MM_ HIENGLISH 
MM_ HIMETRIC 
MM_ LOENGLISH 
MM... LOMETRIC 
MM_ TEXT 

MM_ TWIPS 


When MM_ ISOTROPIC mode is set, an application must call the 
Set WindowExt function before calling Set ViewportExt. 


LONG SetWindowLong(hWnd, nIndez, INewLong) 


This function changes an attribute of the window specified by the hWnd 
parameter. 


Parameter Type/Description 
hWnd HWND Identifies the window. 
nindex int Specifies the attribute to be changed. It must be 
one of the following values: 
Value Meaning 
GWL_STYLE Window style 
GWL-~ WNDPROC _ Long pointer to the window 
procedure 
iNewLong LONG Specifies the replacement value. 


Return Value 


The return value specifies the previous value of the specified long integer. 
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Comments 


To set any extra four-byte values that were allocated when the window- 
class structure was created, use positive offsets as indexes, starting at zero 
for the first four bytes of the extra space. 


If the Set WindowLong function and the GWL_ WNDPROC index are 
used to set a new window function, that function must have the window- 
function form and be exported in the module-definition file of the applica- 
tion. For more information, see the RegisterClass function, earlier in this 
chapter. 


DWORD SetWindowOrg(hDC, X, Y) 


This function sets the window origin of the specified device context. The 
window, along with the device-context viewport, defines how GDI maps 
points in the logical coordinate system to points in the device coordinate 
system. 


The window origin marks the point in the logical coordinate system from 
which GDI maps the viewport origin, a point in the device coordinate sys- 
tem specified by the Set WindowOrg function. GDI maps all other points 
by following the same process required to map the window origin to the 
viewport origin. For example, all points in a circle around the point at the 
window origin will be in a circle around the point at the viewport origin. 
Similarly, all points in a line that passes through the window origin will be 
in a line that passes through the viewport origin. 


Parameter Type/Description 


ADC HDC Identifies the device context. 


xX short Specifies the logical z-coordinate of the new 
origin of the window. 


Y short Specifies the logical y-coordinate of the new 
origin of the window. 


Return Value 
The return value specifies the previous origin of the window. The previous 


y-coordinate is in the high-order word; the previous z-coordinate is in the 
low-order word. 
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void SetWindowPos(hWnd, hWndInsertAfter, 2, y, cz, cy, wF lags) 


This function changes the size, position, and ordering of child, pop-up, 
and top-level windows. Child, pop-up, and top-level windows are ordered 
according to their appearance on the screen; the topmost window receives 
the highest rank, and it is the first window in the list. This ordering is 
recorded in a window list. | 


Parameter Type/Description 


hWnd HWND Identifies the window that will be positioned. 


hWndInsertAfter HWND Identifies a window in the window-manager’s 
list that will precede the positioned window. 


£ int Specifies the z-coordinate of the window’s upper- 
left corner. 

y int Specifies the y-coordinate of the window’s upper- 
left corner. 

cx int Specifies the new window’s width. 

cy int Specifies the new window’s height. 

wk lags WORD Specifies one of eight possible 16-bit values 


that affect the sizing and positioning of the window. It 
must be one of the following values: 


Value Meaning 


SWP_DRAWFRAME Draws a frame (defined in the 
window’s class description) 
around the window. 


SWP_HIDEWINDOW _— Hides the window. 
SWP_ NOACTIVATE Does not activate the window. 


SWP_ NOMOVE Retains current position 
: (ignores the zand y param- 
eters). 
SWP_ NOSIZE Retains current size (ignores 


the cz and cy parameters). 
SWP_ NOREDRAW Does not redraw changes. 


SWP_ NOZORDER Retains current ordering 
(ignores the hWndInsertAfter 
parameter). 


SWP_SHOWWINDOW Displays the window. 
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Return Value 


None 


Comments 


If the SWP_ NOZORDER flag is not specified, Windows places the window 
identified by the hWnd parameter in the position following the window 
identified by the hWndInsertAfter parameter. If hWndInsertAfter is NULL, 
Windows places the window identified by hWnd at the top of the list. If 
hWndInsertAfter is set to 1, Windows places the window identified by 
hWnd at the bottom of the list. 


If the SWP_SHOWWINDOW or the SWP_. HIDEWINDOW flags are set, 
scrolling and moving cannot be done simultaneously. 


All coordinates for child windows are relative to the upper-left corner of 
the parent window’s client area. 


FARPROC SetWindowsHook(nFilter Type, lpFilterF'unc) 


This function installs a filter function in a chain. A filter function pro- 
cesses events before they are sent to an application’s message loop in the 
WinMain function. A chain is a linked list of filter functions of the same 


type. 


Parameter Type/Description 

nFilter Type int Specifies the system hook to be installed. It can be 
any one of the following values: 
Value Meaning 
WH_ CALLWNDPROC 


Installs a window-function filter 
(on debugging versions only). 


WH_ GETMESSAGE Installs a message filter (on 
debugging versions only). 


WH... JOURNALPLAYBACK 
Installs a journaling playback 
filter. 
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WH_ JOURNALRECORD 


Installs a journaling record filter. 
WH_ KEYBOARD Installs a keyboard filter. 
WH_MSGFILTER Installs a message filter. 
WH_SYSMSGFILTER 


Installs a system-wide message 
filter. 


lpnFilterFunc FARPROC #éIs the procedure-instance address of the 
filter function to be installed. See the following “Com- 
ments” section for details. 


Return Value 


The return value points to the procedure-instance address of the previ- 
ously installed filter (if any). It is NULL if there is no previous filter. The 
application that calls the Set WindowsHook function should save this 
return value in memory. The fourth argument of the DefHookProc func- 
tion points to the location in memory where the application saves this 
return value. | 


The WH.. CALLWNDPROC and WH_ GETMESSAGE hooks will affect 
system performance. They are supplied for debugging purposes only. 


Comments 


The system hooks are a shared resource. Installing a hook affects all appli- 
cations. System hooks should be restricted to special-purpose applications 
or as a development aid during debugging of an application. Applications 
that no longer need the hook should remove the filter function. 


To install a filter function, the Set WindowsHook function must receive 
a procedure-instance address of the function, and the function must be 
exported in the application’s module-definition file. A procedure-instance 
address can be created by using the MakeProcInstance function. 


The following section describes how to support the individual hook func- 
tions. 
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WH. CALLWNDPROC 
Windows calls the WH_CALLWNDPROC filter function just before it 


sends any message to a window function. 


The filter function must use the Pascal calling convention and must be r 
declared FAR. The filter function must have the form: 


void FAR PASCAL FilterFunc(nCode, wParam, lParam) 
int nCode; 

WORD wParam; 

DWORD [Param; 


FilterFunc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter . Description 


nCode Specifies whether the filter function should process the 
message or call the DefHookProc function. If the 
nCode parameter is less than zero, the filter function 
should pass the message to DefHookProe without 
further processing. | 


wParam Specifies whether the message is sent by the current | 
task. It is nonzero if the message 1s sent; otherwise, it 1s 
NULL. 

lParam Points to a message structure. 

Comments 


The WH. CALLWNDPROC filter function can examine or modify the 
message as desired. Once it returns control to Windows, the message, with 
any modifications, is passed on to the window function. The filter function 
does not require a return value. 


WEL GETMESSAGE 


Windows calls the WH GETMESSAGE filter function whenever the 
GetMessage function is called. Windows calls the filter function immedi- 
ately after GetMessage has retrieved a message from an application 
queue. The filter function must use the Pascal calling convention and must 
be declared FAR. The filter function must have the following form: 
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void FAR PASCAL FilterFunc(nCode, wParam, lParam) 
int nCode; 

WORD wParam; 

DWORD /Param; 


FilterFunc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Description 


nCode Specifies whether the filter function should process the 
message or call the DefHookProc function. If the 
nCode parameter is less than zero, the filter function 
should pass the message to DefHookProc without 
further processing. 


wParam Specifies a NULL value. 
lParam Points to a message structure. 
Comments 


The WH_ GETMESSAGE filter function can examine or modify the 
message as desired. Once it returns control to Windows, the GetMessage 
function returns the message, with any modifications, to the application 
that originally called it. The filter function does not require a return value. 


The WH_ GETMESSAGE filter is available only with the debugging 


versions of Windows. 


WH_JOURNALPLAYBACK 
Windows calls the WH_ JOURNALPLAYBACK filter function when- 


ever a request for an event message is made. The function is intended to be 
used to supply a previously recorded event message. 


The filter function must use the Pascal calling convention and must be 
declared FAR. The filter function must have the following form: 


DWORD FAR PASCAL FilterFunc(nCode, wParam, lParam); 
int nCode; 

WORD wParam; 

DWORD [Param; 


FulterFunc is a placeholder for the application-supplied function name. 


The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 
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Parameter Description 


nCode Specifies whether the filter function should process the 
message or call the DefHookProc function. If the 
nCode parameter is less then zero, the filter function 
should pass the message to DefHookProce without 
further processing. 


wParam Specifies a NULL value. 

lParam Points to the message being processed by the filter 
function. 

Comments 


The WH. JOURNALPLAYBACK function should copy an event mes- 
sage to the [Param parameter. The message must have been previously 
recorded by using the WH- JOURNALRECORD filter. It should not 
modify the message. The return value should be the amount of time (in 
clock ticks) Windows should wait before processing the message. This time 
can be computed by calculating the difference between the time fields in 
the current and previous event messages. If the function returns zero, the 
message is processed immediately. Once it returns control to Windows, the 
message continues to be processed. If the nCode parameter is HC_ SKIP, 
the filter function should prepare to return the next recorded event mes- 
sage on its next call. 


While the WH. JOURNALPLAYBACK function is in effect, Windows 


ignores all mouse and keyboard input. 


WH. JOURNALRECORD 
Windows calls the WH_ JOURNALRECORD filter function whenever 


it processes a message from the event queue. The filter can be used to 
record the event for later playback. 


The filter function must use the Pascal calling convention and must be 
declared FAR. The filter function must have the following form: 


void FAR PASCAL FilterFunc(nCode, wParam, lParam); 
int nCode3 

WORD wParam; 

DWORD [Param; 


FilterF'unc is a placeholder for the application-supplied function name. 


The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 
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Parameter Description 


nCode Specifies whether the filter function should process the 
message or call the DefHookProc function. If the 
nCode parameter is less than zero, the filter function 
should pass the message to DefHookProc without 
further processing. 


wParam Specifies a NULL value. 
lParam Points to a message structure. — 
Comments 


The WH_ JOURNALRECORD function should save a copy of the 
event message for later playback. It should not modify the message. Once 
it returns contro] to Windows, the message continues to be processed. The 
filter function does not require a return value. 


WH_ KEYBOARD 


Windows calls the WH. KEYBOARD filter function whenever the appli- 
cation calls the GetMessage or PeekMessage function and there is a 
keyboard event (WM_ KEYUP or WM_KEYDOWN) to process. 


The filter function must use the Pascal calling convention and must be 
declared FAR. The filter function must have the following form: 


int FAR PASCAL FilterFunc(nCode, wParam, lParam) 
int nCode; 

WORD wParam; 

DWORD Param; 


FiulterFunc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Description 


nCode Specifies whether the filter function should process the 
message or call the DefHookProc function. If this 
value is HC_NOREMOVE, the application is using the 
PeekMessage function with the PM- NOREMOVE 
option and the message will not be removed from the 
system queue. If this value is less than zero, the filter 
function should pass the message to DefHookProc 
without further processing. 
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wParam Specifies the virtual keycode of the given key. 


[Param Specifies the repeat count, scan code, key-transition 
code, previous key state, and context code, as shown in 
the following list. Bit 1 1s the low-order bit: 


Bit Value 
0-15 Repeat count (the number of times the 


keystroke is repeated as a result of the user 
holding down the key) 


16-23 Scan code (OEM-dependent value) 

24-28 Not used | 

29 Context code (1 if the ALT key was held 
down while the key was pressed, O other- 
wise) 

30 Previous key state (1 if the key was held 
down before the message was sent, 0 if the 
key was up) 

31 Transition state (1 if the key is being 


released, 0 if the key is being pressed) 


Return Value 


The return value specifies what should happen to the message. It 1s zero if 
the message should be processed by Windows; it is 1 if the message should 
be discarded. 


WH_ MSGFILTER 
Windows calls the WH- MSGFILTER filter function whenever a dialog 


box, message box, or menu has retrieved a message, and before it has proc- 
essed that message. The filter allows an application to process or modify 
the messages. 


The filter function must use the Pascal calling convention and must be 
declared FAR. The filter function must have the following form: 


int FAR PASCAL FilterFunc(nCode, wParam, |Param ) 
int Code; 

WORD wParam; 

DWORD [Param 
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FilterFunc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Description 


nCode Specifies the type of message being processed. It must be 
one of the following values: 


Value Meaning 


MSGF_ DIALOGBOX Processing messages inside the 
DialogBox function. 


MSGF_ MENU Processing keyboard and 
mouse messages In menu. 


MSGF_ MESSAGEBOX Processing messages inside the 
MessageBox function. 


If this value is less than zero, the filter function should 
pass this message to DefHookProc without further 


processing. 
wParam Specifies a NULL value. 
[Param Points to the message structure. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
hook function processes the message. Otherwise, it is zero. 


WH_SYSMSGFILTER 
Windows calls the WH_SYSMSGFILTER filter function whenever a 


dialog box, message box, or menu has retrieved a message and before it 
has processed that message. The filter allows an application to process or 
modify messages for any application in the system. 


The filter function must use the Pascal calling convention and must be 
declared FAR. The filter function must have the following form: 


int FAR PASCAL FilterFunc(nCode, wParam, lParam ) 
int nCode; 

WORD wParam; 

DWORD [!Param; 
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FilterFunc is a placeholder for the application-supplied function name. 
The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Description 


nCode Specifies the type of message being processed. It must be 
one of the following values: 


Value Meaning 


MSGF_ DIALOGBOX Processing messages inside the 


Dialog Box function. 


MSGF_ MENU Processing keyboard and 


mouse messages In menu. 


MSGF_ MESSAGEBOX Processing messages inside the 
MessageBox function. 


If this value is less than zero, the filter function should 
pass the message to DefHookProc without further pro- 


cessing. 
wParam Specifies a NULL value. 
‘Param Points to the message structure. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
hook function processes the message. Otherwise, it is zero. 


void SetWindowText(hWnd, IpString) 


This function sets the given window’s caption title (if one exists) to the 
string pointed to by the lpString parameter. If the hWnd parameter is a 
handle to a control, the Set WindowText function sets the text within 
the control instead of within the caption. 


Parameter Type/Description 


hWnd HWND Identifies the window or control whose text 
is to be changed. 


lpString LPSTR Points to a null-terminated character string. 
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Return Value 


None 


WORD SetWindowWord(hWnd, nIndex, wNewWord) 


This function changes an attribute of the window specified by the hWnd 
parameter. 


Parameter Type/ Description 
hWnd HWNOD Identifies the window to be modified. 
nindex int Specifies the word to be changed. It must be one 


of the following values: 
Value Meaning 


GWW_ HINSTANCE 
Instance handle of the module 
that owns the window 


GWW_HWNDPARENT 
Window handle of the parent 
window, if one exists 


GWW-_ ID Control ID of the child window 
wNew Word WORD Specifies the replacement value. 


Return Value 

The return value specifies the previous value of the specified word. 
Comments 

To access any extra two-byte values that were allocated when the 


window-class structure was created, use positive offsets as indexes, 
starting at zero for the first two bytes of the extra space. 


void ShowCaret(hWnd) 


This function shows the system caret on the display at the caret’s current 
position. Once shown, the caret begins flashing automatically. 
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The ShowCaret function shows the caret only if it has a current shape 
and has not been hidden two or more times in a row. If the caret is not 
owned by the given window, the caret is not shown. [f the hWnd parame- 
ter is NULL, the SetCaret function shows the caret only if it is owned 
by a window in the current task. 


Hiding the caret is accumulative. If the HideCaret function has been 
called five times in a row, ShowCaret must be called five times to show 
the caret. 


Parameter Type/Description 


hWnd HWND Identifies the window that owns the caret, or 
is NULL to specify indirectly the owner window in the 
current task. 


Return Value 


None 


Comments 


The system caret is a shared resource. A window should show the caret 
only when it has the input focus or is active. 


int ShowCursor(bShow) 


This function shows or hides the cursor. The ShowCursor function actu- 
ally sets an internal display counter that determines whether the cursor 
should be displayed. If the Skew parameter is nonzero, ShowCursor 
adds one to the display count. If bShow is zero, the display count is 
decreased by one. The cursor is displayed only if the display count 1s 
greater than or equal to zero. Initially, the display count is zero if a mouse 
is installed. Otherwise, it 1s —1. 


Parameter Type/Description 
bShow ~BOOL = Specifies whether the display count is to be 


increased or decreased. The display count 1s increased if 
bShow is nonzero; otherwise, it is decreased. 
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Return Value 


The return value specifies the new display count. 


Comments 


The system cursor is a shared resource. A window that hides the cursor 
should show the cursor before the cursor leaves its client area, or before 
the window relinquishes control to another window. 


void ShowOwnedPopups(h Wnd, fShow) 


This function shows or hides all pop-up windows that are associated with 
the hWnd parameter. If the {Show parameter is nonzero, all hidden pop-up 
windows are shown; if {Show is zero, all visible pop-up windows are hidden. 


Parameter Type/Description 
hWnd HWND Identifies the window that owns the pop-up 
windows that are to be shown or hidden. 


fShow BOOL Specifies whether or not pop-up windows are 
hidden. It is nonzero if all hidden pop-up windows 
should be shown; it is zero if all visible pop-up windows 
should be hidden. 


Return Value 


None 


void ShowScrollBar(hWnd, wBar, fShow) 


This function displays or hides a scroll bar, depending on the value of the 
{Show parameter. If fShow is nonzero, the scroll bar is displayed; if fShow is 
zero, the scroll bar is hidden. 


Parameter Type/ Description 


hWnd HWND Identifies a window that contains a scroll 
bar in its non-client area if the wBar parameter is 
SB_ HORZ, SB_ VERT, or SB. BOTH. If wBar is 
SB. CTL, hWnd identifies a scroll-bar control. 
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wBar WORD Specifies whether the scroll bar is a control or 
part of a window’s non-client area. If it is part of the 
non-client area, wBar also indicates whether the scroll 
bar is positioned horizontally, vertically, or both. It 
must be one of the following values: 


Value Meaning 


SB. BOTH _ Specifies the window’s horizontal and 
vertical scroll bars. 
SB_ CTL Specifies that the scroll bar is a control. 


SB_HORZ _ Specifies the window’s horizontal scroll 


bar. 
SB_ VERT — Specifies the window’s vertical scroll bar. 
fShow BOOL Specifies whether or not Windows hides the 


scroll bar. If fShow is zero, the scroll bar is hidden. 
Otherwise, the scroll bar is displayed. 


Return Value 
None 


Comments 


Unlike the SetScrollBar function, the ShowScrollBar function does not 
destroy a scroll bar’s position and range when it hides the scroll bar. 


BOOL ShowWindow(hWnd, nCmdShow) 


This function displays or removes the given window, as specified by the 
nCmdShow parameter. 


Parameter Type/Description 
hWnd HWND Identifies the window. 
nCmdShow int Specifies how the window is to be shown. It must 


be one of the values shown in Table 3.19. 
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Show Window 


The return value specifies the previous state of the window. It is nonzero if 
the window was previously visible. It is zero if the window was previously 


hidden. 


Comments 


The Show Window function must be called only once per program with 
the nCmdShow parameter from the WinMain function. Subsequent calls 
to Show Window must use one of the values listed above, instead of one 
specified by the nCmdShow parameter from the WinMain function. Table 
3.19 lists the values for the nCmdShow parameter: 


Table 3.19 
Window States 


Value 

5 W-_ HIDE 

9 W_ MINIMIZE 

SW_ RESTORE 

SW_ SHOW 

9 W_ SHOWMAXIMIZED 
SW_SHOWMINIMIZED 
SW_SHOWMINNOACTIVATE 


SW_SHOWNA 


SW_SHOWNOACTIVATE 


SW. SHOWNORMAL 


Meaning 


Hides the window and passes activation to 
another window. 


Minimizes the specified window and 
activates the top-level window in the 
window-manager’s list. 


Same as SW_SHOWNORMAL. 


Activates a window and displays it in its 
current size and position. 


Activates the window and displays it as a 
maximized window. 


Activates the window and displays it as 
iconic. 

Displays the window as iconic. The window 
that is currently active remains active. 


Displays the window in its current state. 
The window that is currently active remains 
active. 


Displays a window in its most recent size 
and position. The window that is currently 
active remains active. 


Activates and displays a window. If the 
window is iconic or zoomed, Windows 
restores it to its original size and position. 
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WORD SizeofResource(hInstance, hResInfo) 
This function supplies the size {in bytes) of the specified resource. It is typ- 


ically used with the AccessResource function to prepare local memory to 
receive a resource from the file. 


Parameter Type/Description 


hInstance HANDLE Identifies the instance of the module whose 
executable file contains the resource. 
hResInfo HANDLE Identifies the desired resource. This han- 


dle is assumed to have been created by using the 
FindResource function. 


Return Value 


The return value specifies the number of bytes in the resource. It 1s zero if 
the resource cannot be found. 


int StartSound( ) 

This function starts play in each voice queue. The StartSound function 
is not destructive, so it may be called any number of times to replay the 
current queues. 


This function has no parameters. 


Return Value 


Although the return-value type is integer, its contents should be ignored. 


int StopSound( ) 


This function stops playing all voice queues, then flushes the contents of 
the queues. The sound driver for each voice is turned off. 


This function has no parameters. 


Return Value 


Although the return-value type is integer, its contents should be ignored. 
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BOOL StretchBlt(hDestDO, X, Y, nWidth, nHeight, hSrcDC, XSrc, YSrc, 
nSreWidth, nSrcHeight, dwRop) 


This function moves a bitmap from a source rectangle into a destination 
rectangle, stretching or compressing the bitmap if necessary to fit the 
dimensions of the destination rectangle. The StretchBlt function uses 
the stretching mode of the destination device context (set by the 
SetStretchBltMode function) to determine how to stretch or compress 
the bitmap. 


StretchBlt moves the bitmap from the source device given by the ASrcDC 
parameter to the destination device given by the hDestDC parameter. The 
XSre, YSre, nSrcWidth, and nSrcHeight parameters define the origin and 
dimensions of the source rectangle. The X, Y, nWidth, and nHeight param- 
eters give the origin and dimensions of the destination rectangle. The ras- 
ter operation specified by the dwRop parameter defines how the source bit- 
map and the bits already on the destination device are combined. 


StretchBlt creates a mirror image of a bitmap if the signs of the 
nsoreWidth and nWidth or nSrcHeight and nHeight parameters differ. If 
nSrc Width and nWidth have different signs, the function creates a mirror 
image of the bitmap along the z-axis. If nSrcHeight and nHeight have 
different signs, the function creates a mirror image of the bitmap along 
the y-axis. 


Parameter Type/Description 

hDestDC HDC Identifies the device context to receive the bit- 
map. 

X short Specifies the logical z-coordinate of the upper- 
left corner of the destination rectangle. 

Y short Specifies the logical y-coordinate of the upper- 
left corner of the destination rectangle. 

n Width short Specifies the width (in logical units) of the desti- 
nation rectangle. 

nHeight short Specifies the height (in logical units) of the des- 

__ tination rectangle. 
hSrcDC HDC Identifies the device context that contains the 


source bitmap. 


481 


StretchBlt 


XSTC short Specifies the logical z-coordinate of the upper- 
left corner of the source rectangle. 

YSre short Specifies the logical y-coordinate of the upper- 
left corner of the source rectangle. 

nSreWidth short Specifies the width (in logical units) of the 
source rectangle. 

nSrcHeight short Specifies the height (in logical units) of the 
source rectangle. 

dwRop DWORD Specifies the raster operation to be per- 


formed. Raster operation codes define how GDI com- 
bines colors in output operations that involve a current 
brush, a possible source bitmap, and a destination 
bitmap. 


For a list of raster-operation codes, see the BitBlt function, earlier in this 
chapter. For a complete list of the operations, see Appendix A, “Binary 
and ‘Ternary Raster-Operation Codes and Definitions.” 


Return Value 


The return value specifies whether the bitmap is drawn. It is nonzero if the 
bitmap is drawn. Otherwise, it is zero. 


Comments 


StretchBlt stretches or compresses the source bitmap in memory, then 
copies the result to the destination. If a pattern is to be merged with the 
result, it is not merged until the stretched source bitmap 1s copied to the 
destination. 


If a brush is used, it is the selected brush in the destination device con- 
text. 


The destination coordinates are transformed according to the destination 
device context; the source coordinates are transformed according to the 
source device context. 


If destination, source, and pattern bitmaps do not have the same color for- 
mat, StretchBlt converts the source and pattern bitmaps to match the 
destination bitmaps. The foreground and background colors of the desti- — 
nation are used in the conversion. 
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If StretchBlt must convert a monochrome bitmap to color, it sets white 
bits (1) to background color and black bits (0) to foreground color. To 
convert color to monochrome, it sets pixels that match the background 
color to white (1), and sets all other pixels to black (0 (0 ). The foreground 
and background colors of the device context with color are used. 


StretchBlt cannot process bitmaps larger than 64K. If a bitmap is larger 
than 64K, it must be subdivided into smaller bitmaps. 


Not all devices support the StretchBlt function. For more information, 
see the RC_ BITBLT a in the aa function, earlier 
in age chapter. — -, net 
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void SwapMouseButton(bSwap) 
This function reverses the meaning of left and right mouse buttons. If the 
bSwap parameter is TRUE, the left button generates right-button mouse 


messages and the right button generates left-button messages. If bSwap is 
FALSE, the buttons are restored to their original meaning. 


Parameter Type/Description 


bSwap BOOL Specifies whether the button meanings are 
reversed or restored. 


Return Value 


None 
Comments 


Button swapping is provided as a convenience to people who use the mouse 
with their left hands. The SwapMouseButton function is usually called 
by the control panel only. Although applications are free to call the func- 
tion, the mouse is a shared resource and reversing the meaning of the 
mouse button affects all applications. 
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int SyncAllVoices( ) 

This function queues a sync mark in each queue. Upon encountering a sync 
mark in a voice queue, the voice is turned off until sync marks are encoun- 
tered in all other queues. This forces synchronization among all voices. 
This function has no parameters. 


Return Value 


The return value specifies the result of the function. It is zero if the func- 
tion is successful. If a voice queue is full, the return value is S-SERQFUL. 
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BOOL TextOut(hDC, X, Y, IpString, nCount) 


This function writes a character string on the specified display, using the 
currently selected font. The starting position of the string is given by the 
Xand Y parameters. 


Parameter Type/Description 

hDC HDC | Identifies the device context. 

X short Specifies the logical #coordinate of the starting 
point of the string. 

Y short Specifies the logical y coordinate of the starting 
point of the string. 

InString LPSTR Points to the character string that is to be 
drawn. 

nCount short Specifies the number of characters in the string. 


Return Value 


The return value specifies whether or not the string is drawn. It is nonzero 
if the string is drawn. Otherwise, it is zero. 


Comments 


Character origins are defined to be at the upper-left corner of the charac- 
ter cell. 


The current position is neither used nor updated by this function. 


void Throw(lpCatchBuf, nThrowBack) 


This function restores the execution environment to the values saved in 
the buffer pointed to by the IpCatchBuf parameter. The execution environ- 
ment is the state of all system registers and the instruction counter. Exe- 
cution continues at the Catch function that copied the environment 
pointed to by IpCatchBuf. The nThrowBack parameter is passed as the 
return value to the Catch function. It can be a nonzero value. 


Parameter Type/Description 
ln CatchBuf LPCATCHBUF Points to an array that contains the 


execution environment. 


nThrowBack int Specifies the value to be returned to the Catch 
function. 
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Return Value 


None 


Comments 


The Throw function is similar to the C run-time LongJmp function 
(which is incompatible with the Windows environment). 


int TranslateAccelerator(hWnd, hAccTable, lpMsg) 


This function processes keyboard accelerators for menu commands. 
The TranslateAccelerator function translates WM_ KE YUP 

and WM_KEYDOWN messages to WM_ COMMAND or 
WM_SYSCOMMAND messages, if there is an entry for the key in 
the application’s accelerator table. The high-order word of the 
lParam parameter of the WM_ COMMAND or WM_SYSCOMMAND 
message contains the value 1 to differentiate the message from 
messages sent by menus or controls. 


WM_ COMMAND or WM_SYSCOMMAND messages are sent directly 
to the window, rather than being posted to the application queue. The 
TranslateAccelerator function does not return until the message is 
processed. 


Accelerator keystrokes that are defined to select items from the system 
menu are translated into WM_SYSCOMMAND messages; all other 
accelerators are translated into WM COMMAND messages. 


Parameter Type/ Description 

hWnd HWND Identifies the window whose messages are to 
be translated. 

hAccTable HANDLE Identifies an accelerator table (loaded by 


using the LoadAccelerators function). 


lnMsg LPMSG Points to a message retrieved by using the 
GetMessage or PeekMessage function. The message 
must be an MSG data structure and contain message 
information from the Windows application queue. 
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Return Value 


The return value specifies the outcome of the function. It is nonzero if 
translation occurs. Otherwise, it is zero. 


Comments 


When TranslateAccelerator returns nonzero (meaning that the message 
is translated), the application should not process the message again by 
using the TranslateMessage function. 


Commands in accelerator tables do not have to correspond to menu items. 


If the accelerator command does correspond to a menu item, the applica- 
tion is sent WM_INITMENU and WM_INITMENUPOPUP messages, just 
as if the user were trying to display the menu. However, these messages 
are not sent if any of the following conditions are present: 


e® The window is disabled. 
e The menu item is disabled. 


e The command is not in the system menu and the window is 
iconic. 


e A mouse capture is in effect (for more information, see the 
SetCapture function, earlier in this chapter). 


If the window is the active window and there is no keyboard focus 
generally true if the window is iconic), then WM_SYSKEYUP and 

SYSKEYDOWN messages are translated instead of WM_ KEYUP 
and WM_KEYDOWN messages. 


If an accelerator keystroke that corresponds to a menu item occurs when 
the window that owns the menu is iconic, no WM. COMMAND message 
is sent. However, if an accelerator keystroke that does not match any 

of the items on the window’s menu or the system menu occurs, a 


WM_ COMMAND message is sent, even if the window is iconic. 


BOOL TranslateMessage(IpMsq) 


This function translates virtual-keystroke messages into character mes- 
sages, as follows: 


e WM_KEYDOWN/WM_ KEYUP combinations produce a 
WM_ CHAR or a DEADCHAR message. 


e WM_SYSKEYDOWN/WM_SYSKEYUP combinations produce 
a WM_SYSCHAR or a WM_SYSDEADCHAR message. 
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The character messages are posted to the application queue, to be read 
the next time the application calls the GetMessage or Peek Message 
function. 


Parameter Type/Description 


lpMsg LPMSG Points to an MSG data structure retrieved 
through the GetMessage or PeekMessage function. 
The structure contains message information from the 
Windows application queue. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
message is translated (that is, character messages are posted to the appli- 
cation queue). Otherwise, it is zero. 


Comments 


The TranslateMessage function does not modify the message given by 
the lpMsg parameter. 


An application should not call TranslateMessage if the application 
processes virtual-key messages for some other purpose. For instance, 
an application should not call the TranslateMessage function if the 
TranslateAccelerator function returns nonzero. 


short TransmitCommChar(nCid, cChar) 


This function marks the character specified by the cChar parameter for 
immediate transmission, by placing it at the head of the transmit queue. 


Parameter Type/Description 

nCid int Specifies the communication device to receive the 
character. 

cChar char Specifies the character to be transmitted. 


Return Value 


The return value specifies the result of the function. It is zero if the func- 
tion is successful. It is negative if the character cannot be transmitted. A 
character cannot be transmitted if the character specified by the previous 
TransmitCommChar function has not yet been sent. 
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short UngetCommChar(nCid, cChar) 


This function places the character specified by the cChar parameter back 
into the receive queue, making this character the first to be read on a sub- 
sequent read from the queue. 


Consecutive calls to the UngetCommChar function are not allowed. The 
character placed back into the queue must be read before attempting to 
place another. 


Parameter Type/Description 


nCid int Specifies the communication device to receive the 
character. 

ceChar char Specifies the character to be placed in the receive 
queue. 


Return Value 


The return value specifies the outcome of the function. It is zero if the 
function is successful. It is negative if an error occurs. 


BOOL UnhookWindowsHook(nHook, IpfnHook) 


This function removes the Windows hook function pointed to by the 
lofnHook parameter from a chain of hook functions. A Windows hook func- 
tion processes events before they are sent to an application’s message loop 
in the WinMain function. 


Parameter Type/Description 

nHook int Specifies the type of hook function removed. It 
may be one of the following values: 
Value Meaning 
WEH_ CALLWNDPROC 


Installs a window-function filter 
(on debugging versions only). 


WH_ GETMESSAGE 
Installs a message filter (on debugging 
versions only). 


WH_ JOURNALPLAYBACK 
Installs a journaling playback filter. 
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WH... JOURNALRECORD 
Installs a journaling record filter. 


WH_ KEYBOARD 
Install a keyboard filter. 


WH_ MSGFILTER 


Installs a message filter. 


lnfnHook FARPROC Is the procedure-instance address of the 
hook function. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
hook function is successfully removed. Otherwise, 1t is zero. 


int UnionRect(IpDestRect, IpSrc1Rect, IpSrc2Rect) 


This function creates the union of two rectangles. The union is the small- 
est rectangle that contains both source rectangles. 


Parameter Type/Description 

IpDestRect LPRECT Points to the RECT data structure that 
is to receive the new union. 

loSrciRect LPRECT Points toa RECT data structure that 
contains a source rectangle. 

lnSrc2Rect LPRECT Points toa RECT data structure that 


contains a source rectangle. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
union is not empty. It is zero if the union is empty. 


HANDLE UnlockData(Dummy) 


This macro unlocks the current data segment. It is intended to be used by 
modules that have movable data segments. 
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Parameter Type/Description 
Dummy int Is not used; can be set to zero. 


Return Value 


None 


BOOL UnlockResource(hResData) 


This function unlocks the resource specified by the hResData parameter 
and decreases the memory block’s reference count by one. The block is 
completely unlocked and subject to moving or discarding, if the reference 
count is decreased to zero. 


Parameter Type/Description 
hResData HANDLE Identifies the global memory block to be 
unlocked. 


Return Value 


The return value specifies the outcome of the function. It is zero if the 
block’s reference count is decreased to zero. Otherwise, it is nonzero. 


HMEM UnlockSegment(wSegment) 

This function unlocks the segment whose segment address is specified by 
the wSegment parameter. If wSegment is -1, the UnlockSegment function 
unlocks the current data segment. 


Parameter Type/Description 


wSegment WORD Specifies the segment address of the segment 
to be unlocked. 


Return Value 


The return value identifies the unlocked segment. 
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BOOL UnrealizeObject(hBrush) 


This function directs GDI to reset the origin of the given brush the next 
time it is selected. 


Parameter Type/Description 
hBrush HBRUSH Identifies the brush to be reset. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the 
function is successful. Otherwise, it 1s zero. 


Comments 
The UnrealizeObject function should not be used with stock objects. 


This function must be called whenever a new brush origin is set (by means 
of the SetBrushOrigin function). 


The brush specified by the hBrush parameter must not be the currently 
selected brush of any display context. 


void UpdateWindow(hWnd) 

This function updates the client area of the given window by sending a 
WM_ PAINT message to the window if the update region for the window 
is not empty. The UpdateWindow function sends a WM. PAINT mes- 


sage directly to the window function of the given window, bypassing the 
application queue. If the update region is empty, no message is sent. 


Parameter Type/Description 
hWnd HWND Identifies the window to be updated. 


Return Value 


None 
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LPSTR ValidateFreeSpaces( ) 


This function checks free segments in memory for valid contents. In the 
debugging version of Windows, the kernel fills all the bytes in free seg- 
ments with the hexadecimal value C. This function begins checking for 
valid contents (OCH) in the free segment with the lowest address, and con- 
tinues checking until it finds an invalid byte or until it has determined 
that all free space contains valid contents. 


This function has no parameters. 


Return Value 


The return value points to the first invalid byte encountered. It is NULL if 
there are no invalid bytes. 


void ValidateRect(hWnd, lpRect) 


This function validates the client area within the given rectangle by 
removing the rectangle from the update region of the given window. If 
the lpRect parameter is NULL, the entire window is validated. 


Parameter Type/Description 

hWnd HWND Identifies the window whose update region is 
to be modified. 

lpRect LPRECT Points toa RECT data structure that 


contains the rectangle (in client coordinates) to be 
removed from the update region. 


Return Value 


None 


Comments 


The BeginPaint function automatically validates the entire client area. 
Neither the ValidateRect nor ValidateRgn function should be called if 
a portion of the update region needs to be validated before the next 

WML_ PAINT message is generated. 


Windows continues to generate WM_ PAINT messages until the current 
update region is validated. 
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void ValidateRgn(h Wnd, hRgn) 


This function validates the client area within the given region by removing 
the region from the current update region of the given window. If the hRkgn 
parameter is NULL, the entire window is validated. 


Parameter Type/ Description 

hWnd HWND Identifies the window whose update region is 
to be modified. 

hEtgn HRGN Identifies a region that defines the area to be 
removed from the update region. 

Return Value 

None 

Comments 


The given region must have been created previously by means of a region 
function (for more information, see Chapter 2, “Functions Overview’ ). 
The region coordinates are assumed to be client coordinates. 
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void WaitMessage( ) 

This function yields control to other applications when an application 

has no other tasks to perform. The WaitMessage function suspends the 
application and does not return until a new message is placed in the appli- 
cation’s queue. 

This function has no parameters. 


Return Value 


None 


Comments 
The following construction 1s equivalent to a call to GetMessage: 


if (!PeekMessage(...)) 
WaitMessage (); 


The GetMessage, PeekMessage, and WaitMessage functions yield 
control to other applications. These calls are the only way to let other 
applications run. If your application does not call any of these functions 
for long periods of time, other applications cannot run. 


When GetMessage, PeekMessage, and WaitMessage yield control to 
other applications, the stack and data segments of the application calling 
the function may move in memory to accommodate the changing memory 
requirements of other applications. If the application has stored long 
pointers to objects in the data or stack segment (that is, global or local 
variables), these pointers can become invalid after a call to GetMessage, 
PeekMessage, or WaitMessage. 


int WaitSoundState(nState) 
This function waits until the play driver enters the specified state. 
Parameter Type/ Description 


nState int Specifies the state of the voice queues. It can be 
any one of the following values: 
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Value Meaning 


S_ALLTHRESHOLD All voices have reached threshold. 


S_QUEUEEMPTY All voice queues are empty and 
sound drivers turned off. 


S_THRESHOLD A voice queue has reached thresh- 


old, and returns voice. 


Return Value 


The return value specifies the result of the function. It is zero if the func- 
tion is successful. If the state is not valid, the return value is S-SERDST. 


HWND WindowFromPoint( Point) 


This function identifies the window that contains the given point; point 
must specify the screen coordinates of a point on the screen. 


Parameter Type/Description 


point POINT Specifies a POINT data structure that 
defines the point to be checked. 


Return Value 


The return value identifies the window in which the point lies. It is NULL 
if no window exists at the given point. 


short WriteComm(nCid, IpBuf, nSize) 


This function writes the number of characters specified by the nSize 
parameter to the communication device specified by the nCid parameter 
from the buffer pointed to by the /pBuf parameter. 


Parameter Type/Description 
nCid int Specifies the device to receive the characters. 
lpBuf LPSTR Points to the buffer that contains the charac- 


ters to be written. 


nSize int Specifies the number of characters to write. 
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Return Value 


The return value specifies the number of characters actually written. 
When an error occurs, the return value is set to a value less than zero, 
making the absolute value of the return value the actual number of char- 
acters written. The cause of the error can be determined by using the 
GetCommError function to retrieve the error code and status. 


Comments 


The WriteComm function will delete data in the transmit queue if there 
is not enough room in the queue for the additional characters. Applica- 
tions should check the available space in the transmit queue with the 
GetCommError function before calling WriteComm. Also, applica- 
tions should use the OpenComm function to set the size of the transmit 
queue to an amount no smaller than the size of the largest expected out- 
put string. 


BOOL WriteProfileString(lpApplicationName, IpKeyName, IpString) 


This function copies the character string pointed to by the lpString param- 
eter into the Windows initialization file, win.enz. It searches win.ini for the 
key named by the IpKeyName parameter under the application heading 
specified by the lpApplicationName parameter. If there is no match, it adds 
a new string entry to the user profile. If there is a matching key, the func- 
tion replaces that key’s value with /pString. 


If there is no application field for lpApplicationName, this function creates 
a new application field and places an appropriate key-value line in that 
field of wen.anz. 


A string entry in win.int has the following form: 


\epelicagn name| 
eyname = value 
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BOOL Yield( ) 

This function halts the current task and starts any waiting task. 
This function has no parameters. 

Return Value 


The return value specifies the outcome of the function. It is nonzero if a 
waiting task is started. Otherwise, it 1s zero. 


Comments 
Applications that contain windows should use a DispatchMessage, 
PeekMessage, or TranslateMessage loop rather than calling the Yield 


function directly. The PeekMessage loop handles message synchroniza- 
tion properly and yields at the appropriate times. 
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4.1 Introduction 


Messages Overview 


This chapter describes groups of related Microsoft Windows messages. 
Each section states the purpose of the message group, lists the messages in 
the group, and describes each message. Some of the sections contain addi- 


tional information. 


4.2 Window-Management Messages 


Window-management messages are sent by Windows to an application 
when the state of a window changes. The following list briefly describes 


each window-management message: 
Message 
WML. ACTIVATE 


WM_ ACTIVATEAPP 


WML_ CLOSE 
WM_ CREATE 


WM_ CTLCOLOR 


WML DESTROY 


WM ENABLE 


WM_ ENDSESSION 


Description 


Sent when a window becomes active 
or inactive. 


Sent when the window being acti- 
vated belongs to a different appli- 
cation than the window that was 
previously active. 


Sent whenever the window is closed. 


Sent when the CreateWindow 
function is called. 


Sent to the parent window of a 
predefined control or message box 
when the control or message box 
is about to be drawn. 


Sent when the Destroy Window 
function is called, after the window 
has been removed from the screen. 


Sent after a window has been 
enabled or disabled. 


Tells an application that has 
responded nonzero to a 

WM_ QUERYENDSESSION 
message whether the session is 
actually being ended. 
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WM_ ERASEBKGND 

WM_ GETDLGCODE 

WM_ GETTEXT 

WM... GETTEXTLENGTH 
WML. KILLFOCUS 

WM_ MOVE 

WM PAINT 

WM_ QUERYENDSESSION 


WM. QUERYOPEN 


WM_ QUIT 
WM_SETFOCUS 
WM_SETREDRAW 
WM_SETTEXT 

WM. SETVISIBLE 
WM_SHOWWINDOW 


WM_ SIZE 
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Sent when the window background 
needs to be erased. 


Sent to a control by the Windows 
dialog manager. 


Copies the text that corresponds to a 
window. 


Retrieves the length (in bytes) of the 
text associated with a window. 


Sent immediately before a window 
loses the input focus. 


Sent when a window is moved. 


Sent whenever Windows or an appli- 
cation makes a request to repaint a 
portion of an application’s window. 


Sent when the user chooses the End 
Session command. 


Sent to an icon when the user 
requests that the icon be opened 
into a window. 


Indicates a request to terminate an 
application. 


Sent after a window receives the 
input focus. 


Sets or clears the redraw flag, which 
determines whether or not updates 
to a control are displayed. 


Sets the text of a window. 


Sent immediately before a window is 
made visible or is hidden. 


Sent whenever a window is to be hid- 
den or shown. 


Sent after the size of a window has 
been changed. 
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4.3 Initialization Messages 


Initialization messages are sent by Windows when an application creates a 
menu or dialog box. The following list briefly describes each initialization 
message: 


Message Description 

WML INITDIALOG | Sent immediately before a dialog box 
is displayed. 

WM_ INITMENU Requests that a menu be initialized. 

WM... INITMENUPOPUP Sent immediately before a pop-up 


menu is displayed. 


4.4 Input Messages 


Input messages are sent by Windows when an application receives input 
through the mouse, keyboard, scroll bars, or system timer. The following 
list briefly describes each input message: 


Message Description 

WM_ CHAR Results when a WM_KEYUP and 
a WM_KEYDOWN message are 
translated. 

WM. COMMAND Sent when the user selects an item 


from a menu, when a control passes 
a message to its parent window, or 
when an accelerator keystroke is 


translated. 
WML DEADCHAR Results when a WM_KEYUP and 
| a WM_KEYDOWN message are 
translated. 
WM... HSCROLL Sent when the user clicks the hor- 


izontal scroll bar with the mouse. 
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WM_KEYDOWN 


WM_ KEYUP 


WM_. LBUTTONDBLCLIt 


WM. LBUT'TTONDOWN 


WM... LBUTTONUP 


WM_ MBUTTONDBLCLKI 


WM MBUTTONDOWN 


WM_ MBUTTONUP 


WM~ MOUSEMOVE 
WM_ RBUTTONDBLCLK 


WM RBUTTONDOWN 


WM_RBUTTONUP 


WM. TIMER 


WM_ VSCROLL 
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Sent when a non-system key is 
pressed. 


Sent when a non-system key is 
released. 


Sent when the user double-clicks the 
left mouse button. 


Sent when the user presses the left 
mouse button. 


Sent when the user releases the left 
mouse button. 


Sent when the user double-clicks the 
middle mouse button. 


Sent when the user presses the mid- 
dle mouse button. 


Sent when the user releases the mid- 
dle mouse button. 


Sent when the user moves the mouse. 


Sent when the user double-clicks the 
right mouse button. 


Sent when the user presses the right 
mouse button. 


Sent when the user releases the right 
mouse button. 


Sent when the time limit set for a 
given timer has elapsed. 


Sent when the user clicks the vertical 
scroll bar with the mouse. 
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4.5 System Messages 


System messages are sent by Windows to an application when a user 
accesses a window’s system menu, scroll bars, or size box. Although an 
application can process these messages, most applications pass them on 
to the DefWindowProc function for default processing. The following 
list briefly describes each system message: 


Message Description 


WM_ ASKCBFORMATNAME Sent when the clipboard contains a 
data handle for the CF_ OWNER- 
DISPLAY format, to request the 
format name. 


WM_ CHANGECBCHAIN Notifies the first window in the clip- 
board viewer chain that a window is 
being removed from the clipboard 
viewer chain. 


WM_ DESTROYCLIPBOARD Sent to the clipboard owner when the 
clipboard is emptied through a call 
to the EmptyClipboard function. 


WM_ DRAWCLIPBOARD Sent to the first window in the clip- 
board viewer chain whenever the 
contents of the clipboard change. 


WM. HSCROLLCLIPBOARD Sent when the clipboard contains a 
data handle for the CF_ OWNER- 
DISPLAY format and an event 
occurs in the clipboard application’s 
horizontal scroll bar. 


WM. PAINTCLIPBOARD Sent when the clipboard contains a 
data handle for the CF_ OWNER- 
DISPLAY format and the clipboard 
application’s client area needs 
repainting. 


WM_ RENDERALLFORMATS Sent to the application that owns the 
clipboard when the application is 
being destroyed. 


WM. RENDERFORMAT Requests that the clipboard owner 
format the data last copied to the 
clipboard. 

WM_ SIZECLIPBOARD Sent when the clipboard contains a 


data handle for the CF_ OWNER- 
DISPLAY format and the clipboard 
application window has changed size. 
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WM_SYSCHAR Results when a WM_SYSKEYUP 
and a WM_SYSKEYDOWN message 
are translated. 


WM_SYSCOMMAND Sent when the user selects a com- 
mand from the system menu. ae 
WM_SYSDEADCHAR Results when a WM_SYSKEYUP 


and a WM_SYSKEYDOWN message 


are translated. 


WM_SYSKEYDOWN Sent when the user holds down the 
ALT key and then presses another 
key. 

WM_SYSKEYUP Sent when the user releases a key 


that was pressed while the ALT key 
was held down. 


WM_SYSTEMERROR Sent to all top-level windows when 
an out-of-memory system error 
occurs. 

WM_ VSCROLLCLIPBOARD Sent when the clipboard contains a 


data handle for the CF_ OWNER- 
DISPLAY format and an event 
occurs in the clipboard application’s 
vertical scroll bar. 


4.6 Clipboard Messages 


Clipboard messages are sent by Windows to an application when other 
applications try to access a window’s clipboard. The following list briefly 
describes each clipboard message: 


Message Description 

WM_ ASKCBFORMATNAME Requests the name of the 
CF... OWNERDISPLAY format. 

WM CHANGECBCHAIN Notifies viewing-chain members of a 
change in the chain. 

WM. DESTROYCLIPBOARD Signals that the contents of the clip- 
board are being destroyed. 

WM_ DRAWCLIPBOARD Signals an application to notify the 


next application in the chain of a 
clipboard change. 
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WML HSCROLLCLIPBOARD 


WML PAINTCLIPBOARD 


WM_ RENDERALLFORMATS 


WML RENDERFORMAT 


WML SIZECLIPBOARD 


WM. VSCROLLCLIPBOARD 
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Requests horizontal scrolling for the 
CF..OWNERDISPLAY format. 


Requests painting of the 
CF_ OWNERDISPLAY format. 


Notifies the clipboard owner that it 
must render the clipboard data in all 
possible formats. 


Notifies the clipboard owner that it 
must format the last data copied to 
the clipboard. 


Notifies the clipboard owner that the 
clipboard application’s window size 
has changed. 


Requests vertical scrolling for the 


CF_OWNERDISPLAY format. 


4.7 System-Information Messages 


System-information messages are sent by Windows when an application or 
a user makes a system-wide change that affects other applications. The fol- 
lowing list briefly describes each system-information message: 


Message 
WM. DEVMODECHANGE 


WML FONTCHANGE 


WM_SYSCOLORCHANGE 


WM_ SYSTEMERROR 


WML. TIMECHANGE 


WM WININICHANGE 


Description 


Sent to all top-level windows when the 
user changes device-mode settings. 


Sent when the pool of font resources 
changes. 


Sent to all top-level windows when a 
change is made in the system color 
setting. 


Sent to all top-level windows when an 
out-of-memory system error occurs. 


Sent when an application makes a 
change or set of changes to the system 
time. 


Sent when the Windows initialization 
file, win.ini, changes. 
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4.8 Control Messages 


Control messages are predefined window messages that direct a control to 
carry out a specified task. Applications send control messages to a control 
by using the SendMessage function. The control carries out the specified 
task and returns a value that indicates the result. Sections 4.8.1 through 
4.8.3 briefly describe the control messages for each control class. 


4.8.1 Button-Control Messages 


Button-control messages are sent by an application to a button control. 
The following list briefly describes each button-control message: 


Message Description 

BM_ GETCHECK Determines whether a radio button or check 
box 1s checked. 

BM_ GETSTATE Returns nonzero if the cursor is over the 


button and the user presses a mouse button 
or the SPACEBAR. 


BM_SETCHECK Checks or removes the check from a radio 
button or check box. 
BM_SETSTATE Highlights a button or check box. 


4.8.2 Edit-Control Messages 


Edit-control messages are sent by an application to an edit control. 

In addition to the messages described below, the WM_ ENABLE, 

WM. GETTEXT, WM_ GETTEXTLENGTH, WM_ KILLFOCUS, 
WM- SETFOCUS, WM_SETREDRAW, and WM_SETTEXT window 
messages can also be used. The following list briefly describes each edit- 
control message: 


Message Description 

EM. CANUNDO Determines whether or not an edit control 
can respond correctly to an EM_ UNDO 
message. 

EM... FMTLINES Directs the edit control to add or remove the 
end-of-line character from wordwrapped text 
lines. 
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EM_ GE'THANDLE 


EM_ GETLINE 
EM_ GETLINECOUNT 


EM_ GETRECT 


EM_ GETSEL 


EM_ LIMITTEXT 


BMW LINEINDEX 


EM_ LINELENGTH 


EM_ LINESCROLL 


EM_ REPLACESEL 
EM_ SCROLL 


EM. SETFONT 
EM_ SETHANDLE 


EM_ SETRECT 


EM_ SETRECTNP 


EM_ SETSEL 


EM_ UNDO 


WM_ CLEAR 
WM. COPY 
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Returns the data handle of the buffer used 
to hold the contents of the control window. 


Copies a line from the edit control. 


Returns the number of lines of text in the 
edit control. 


Returns the formatting rectangle of the edit 
control. 


Returns the starting and ending character 
positions of the current selection. 


Limits the length of the text (in bytes) the 
user may enter. 


Returns the number of characte: positions 
that occur before the first character in a 
given line. 


Returns the length of a line (in bytes) in the 
edit control’s text buffer. 


Scrolls the contents of the edit control by 
the given number of lines. 


Replaces the current selection with new text. 


Directs the edit control to scroll the contents 
of its window vertically. 


Sets the edit-control font. 


Establishes the text buffer used to hold the 
contents of the edit-control window. 


Sets the formatting rectangle for an edit 
control. 


Identical to EM_SETRECT, except that the 


control is not repainted. 


Selects all characters in the current text that 
are within the starting and ending character 
positions given by the /Param parameter. 


Undoes the last edit to the edit control. 
Deletes the current selection. 


Sends the current selection to the clipboard 
in CF. TEXT format. 
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WM_ CUT 


WML PASTE 


Sends the current selection to the clipboard 
in CF_ TEXT format, and then deletes the 


selection from the control window. 


Inserts the data from the clipboard into 
the control window at the current cursor 
position. 


4.8.3 List-Box Messages 


List-box messages are sent by an application to a list box. The following 
list briefly describes each list-box message: 


Message 


LB_ ADDSTRING 
LB_ DELETESTRING 
LB_ DIR 


LB. GETCOUNT 
LB. GETCURSEL 


LB_ GETSEL 
LB_ GETTEXT 


LB_ GETTEXTLEN 
LB_INSERTSTRING 
LB_ SELECTSTRING 


LB. SETCURSEL 


LB_SETSEL 
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Description 


Adds a string to the list box. 
Deletes a string from the list box. 


Adds a list of the files from the current 
directory to the list box. 


Returns a count of the number of items in 
the list box. 


Returns the index of the currently selected 
item, if any. 


Returns the selection state of an item. 


Copies a string from the list box into a 
buffer. 


Returns the length of a string in the list box. 


Inserts a string in the list box. 


Changes the current selection to the first 
string that has the specified prefix. 


Selects a string and scrolls it into view, if 
necessary. 


Sets the selection state of a string. 
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4.9 Notification Messages 


Notification messages notify a control’s parent window of actions that 
occur within a control. Sections 4.9.1 through 4.9.3 briefly describe the 
notification messages for each notification class. 


Button and edit controls use the WM_ COMMAND message to notify the 
parent window of actions that occur within the control. Unless an excep- 
tion is noted, the wParam parameter of the WM— COMMAND message 
contains the control ID, the low-order word of the /Param parameter con- 
tains the control-window handle, and the high-order word of [Param 
contains the control notification code. 


4.9.1 Button Notification Codes 


The following notification codes apply only to buttons that have 
BS— USERBUTTON style: 


Message Description 

BN_ CLICKED Indicates that the button has been clicked. 
BN_ DISABLE Requests that a disabled button be drawn. 
BN_ HILITE Requests that the button be made visible. 
BN PAINT Requests that the button be repainted. 
BN_ UNHILITE Requests that the button be made invisible. 


BA) . DAUBLECLICKED Jucrcatte tak the bulbn has been clorbleclehed 
4.9.2 Edit-Control Notification Codes 


The following notification codes apply to edit controls: 


Message Description 

EN CHANGE Indicates that the user has taken some 
action that may have changed the content 
of the text. 

EN_ ERRSPACE Indicates that the edit control is out of 
space. 
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EN. HSCROLL Indicates that the user has clicked the edit 
control’s horizontal scroll bar with the 
mouse; the parent window is notified before 
the screen is updated. 


EN. KILLFOCUS Indicates that the edit control has lost the 


input focus. 

EN. SETFOCUS Indicates that the edit control has obtained 
the input focus. 

EN. VSCROLL Indicates that the user has clicked the edit 


control’s vertical scroll bar with the mouse; 
the parent window is notified before the 
screen is updated. 


4.9.3 List-Box Notification Codes 


The following notification codes apply only to list-box controls that have 
LBS_ NOTIFY style: 


Message Description 

LBN_ DBLCLK Sent when the user double-clicks a string 
with the mouse. 

LBN- ERRSPACE Sent when the system is out of memory. 

LBN- SELCHANGE Sent when the selection has been changed. 


4.10 Scroll-Bar Messages - 


There are two messages in the scroll-bar group: WM HSCROLL and 
WM_VSCROLL. Scroll-bar controls send these messages to their parent 
windows whenever the user clicks in the control. The wParam parameter 
contains the same values as those defined for the scrolling messages of a 
standard window. The high-order word of the [Param parameter contains 
the window handle of the scroll-bar control. 
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4.11 Non-Client-Area Messages 


Non-client-area messages are sent by Windows to create and maintain the 
non-client area of an application’s window. Normally, applications do not 
process these messages, but send them on to the DefWindowProc func- 
tion for processing. The following list briefly describes each non-client-area 


message: 
Message 
WM_ NCACTIVATE 


WM NCCALCSIZE 
WM_ NCOCREATE 


WM_ NCDESTROY 
WM_~ NCHITTEST 


WM_ NCLBUTTONDBLCLK 


WM_ NCLBUTTONDOWN 


WM_ NCLBUTTONUP 


WML NCMBUTTONDBLCLK 


WM. NCMBUTTONDOWN 


Description 


Sent to a window when its caption bar or 
icon needs to be changed to indicate an 
active or inactive state. 


Sent when the size of a window’s client 
area needs to be calculated. 


Sent prior to the WM_CREATE mes- 
sage when a window is first created. 


Sent after the WM_ DESTROY message. 


Sent to the window that contains the 
mouse cursor (unless a window has cap- 
tured the mouse). 


Sent to a window when the left mouse 
button is double-clicked while the mouse 
cursor is In a non-client area of the 
window. 


Sent to a window when the left mouse 
button is pressed while the mouse cursor 
is In a non-client area of the window. 


Sent to a window when the left mouse 
button is released while the mouse cursor 
is In a non-client area of the window. 


Sent to a window when the middle 
mouse button is double-clicked while 
the mouse cursor is in a non-client 
area of the window. 


Sent to a window when the middle 
mouse button is pressed while the 
mouse cursor Is in a non-client area 
of the window. 
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WM. NCMBUTTONUP Sent to a window when the left mouse 
button is released while the mouse cursor 
is in a non-client area of the window. 


WM. NCMOUSEMOVE Sent to a window when the mouse cursor 
is moved in a non-client area of the 
window. 

WML_ NCPAINT Sent to a window when its border needs 
painting. 


WM..NCRBUTTONDBLCLK — Sent to a window when the right mouse 
. button is double-clicked while the mouse 
| cursor is in a non-client area of the 
window. 


WM_ NCRBUTTONDOWN Sent to a window when the right mouse 
button is pressed while the mouse cursor 
is in a non-client area of the window. 


WM. NCRBUTTONUP Sent to a window when the right mouse 
button is released while the mouse cursor 
is in a non-client area of the window. 
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Messages Directory 


Introduction 


Microsoft Windows communicates with applications through formatted 
window messages. These messages are sent to an application’s window 
function for processing. 


A message consists of three parts: a message number, a word param- 
eter, and a long parameter. Message numbers are identified by predefined 
message names. The message names begin with letters that suggest the 
meaning or origin of the message. The word and long parameters, named 
wParam and [Param respectively, contain values that depend on the mes- 
sage number. If a given message does not use the parameter, the param- 
eter 18 set to zero. 


The (Param parameter often contains more than one type of information. 
For example, the high-order word may contain a handle to a window and 
the low-order word may contain an integer value. The HIWORD and 
LOWORD utility macros can be used to extract the high- and low-order 
words of the [Param parameter. The HIBYTE and LOBYTE utility 
macros can also be used with HIWORD and LOWORD to access any 
of the bytes. Casting can also be used. 


There are four ranges of message numbers, as shown in the following list: 


Range Meaning 

0 to WM_ USER — 1 Reserved for use by Windows. 

WM... USER to 7FFF Integer messages for use by applications. 
(hexadecimal) 


8000 to BFFF (hexadecimal) Reserved for use by Windows. 
C000 to FFFF (hexadecimal) String messages for use by applications. 


Message numbers in the first range (0 to WM_ USER — 1) are defined by 
Windows. Values in this range that are not explicitly defined are reserved 
for future use by Windows. This chapter describes messages in this range. 


Message numbers in the second range (WM_ USER to 7FFF) can be 
defined and used by an application to send messages within the applica- 
tion. These messages should not be sent to other applications unless the 
applications have been designed to exchange messages and to attach the 
same meaning to the message numbers. 


Message numbers in the third range (8000 to BFFF) are reserved for future 
use by Windows. 
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Message numbers in the fourth range (C000 to FFFF) are defined when an 

application calls the Register WindowMessage function to obtain a mes- 
sage number for a string. All applications that register the identical string 
can use the associated message number for exchanging messages with each 
other. The actual message number, however, is not a constant and cannot 

be assumed to be the same in different window sessions. 


This chapter lists messages in alphabetical order. For more information 
about messages, see Chapter 4, “Messages Overview.” 
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BM_GETSTATE 


BM_ GETCHECK 


This message determines whether a radio button or check box is checked. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 
Return Value 


The return value is nonzero if the radio button or check box is checked. 
Otherwise, it is zero. The BM. GETCHECK message always returns zero 
for a push button. 


BM_GETSTATE 


This message determines the state of a button when the user presses a 
mouse button or the SPACEBAR. 


Parameter Description 
wParam Is not. used. 
lParam Is not used. 


Return Value 


The BM_ GETSTATE message returns a nonzero value if one of the fol- 
lowing occurs: 


e A push button is highlighted. 


e The user presses a mouse button or the SPACEBAR when a button 
has the input focus. 


e The user presses a mouse button when the mouse cursor is over a 
button. 


Otherwise, BM GETSTATE returns zero. 
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BM_SETCHECK 


BM_ SETCHECK 


This message checks or removes the checkmark from a radio button or 
check box. 


Parameter Description 


wParam Specifies whether to place or remove a checkmark beside 
the button or box. If the wParam parameter is nonzero, 
a checkmark is placed; if it is zero, the checkmark (if 
any) is removed. For three-state buttons, if wParam is 1, 
a checkmark is placed beside the button. If wParam is 2, 
the button is grayed. If wParam is zero, the button 1s 
returned to its normal state (no checkmark or graying). 


lParam Is not used. 


Comments 


The BM_SETCHECK message has no effect on push buttons. 


BM_SETSTATE 


This message displays a button or check box. 

Parameter Description 

wParam Specifies the highlighting action to be taken. If the 
wParam parameter is nonzero, the button 1s highlighted 


(the interior is drawn using inverse video). If wParam is 
zero, the button is drawn in its regular state. 


lParam Is not used. 


Comments 


Push buttons cannot be highlighted. 


BM_SETSTYLE 
This message alters the style of buttons. If the style contained in the 


wParam parameter differs from the existing style, the button is redrawn 
in the new style. 
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_ ne. 


BM_SETSTYLE 


Parameter Description 

wParam Specifies the style value. For a complete description of 
possible button styles, see Table 5.1. 

lParam Is not used. 

Comments 


Table 5.1 describes the available button styles: 


Table 5.1 

Button Styles 

Value Meaning 

BS_. AUTOCHECKBOX Identical to BS. CHECKBOX, except that the 


button automatically toggles its state whenever 
the user clicks it. 


BS_ AUTORADIOBUTTON Identical to BS_ RADIOBUTTON, except that 
the button is checked, the application is notified 
by BN- CLICKED, and the checkmarks are 
removed from all other radio buttons in the 


group. 
BS_ AUTO3STATE Identical to BS. 3STATE, except that the button 
automatically toggles its state when the user 
clicks it. 
BS_. CHECKBOX Designates a small rectangular button that may 


be checked; its border is bold when the user clicks 
as button. Any text appears to the right of the 
utton. 


BS_ DEFPUSHBUTTON Designates a small elliptical button with a bold 
border. This button represents the default user 
response. Any text is displayed within the button. 
Windows sends a message to the parent window 
when the user clicks the button. 


BS_ GROUPBOX Designates a rectangle into which other buttons 
are grouped. Any text 1s displayed in the rect- 
angle’s upper-left corner. 


BS_ LEF TTEXT Causes text to appear on the left side of the radio 
button or check-box button. Use this style with 
the BS. CHECKBOX, BS_ RADIOBUTTON, or 
BS_ 3STATE styles. 


BS_ PUSHBUTTON Designates a small elliptical button that contains 
the given text. The control sends a message to its 
parent window whenever the user clicks the 
button. 
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BM_SETSTYLE 


Table 5.1 (continued) 


Value Meaning 


BS_ RADIOBUTTON _ Designates a small circular button whose border 
becomes bold when the user clicks it. In addition, 
to make the border bold, Windows sends a 
message to the button’s parent window notifying 
it that a click occurred. On the next click, 
Windows makes the border normal again and 
sends another message. 

BS_ 3STATE Identical to BS. CHECKBOX, except that a 
button can be grayed as well as checked. The 


grayed state typically is used to show that a 
check box has been disabled. 


BS_USERBUTTON Designates a user-defined button. The parent 
window is notified when the button is clicked. 
Notification includes a request to paint, invert, 
and disable the button. 


BN_ CLICKED 


This code specifies that the user has clicked a button. The parent window 
receives the code through a WM. COMMAND message from a button 
control. 


Parameter Description 

wParam Contains the wParam parameter of the 
WM. COMMAND message, and specifies the 
control ID. 

lParam Contains an edit-control window handle in its 


low-order word and the button window handle 
in its high-order word. 


Comments 
Disabled buttons will not send a BN. CLICKED notification message 


to a parent window. This code applies only to buttons that have 
BS_ USERBUTTON style. 
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BN DOUBLECLICKED 


BN DISABLE 


This code specifies a request to draw a disabled button. The control’s 
parent window receives this code through a WM—~ COMMAND message 
from the control. 


Parameter Description 

wParam Contains the wParam parameter of the 
WM_~ COMMAND message, and specifies the 
control ID. | 

(Param Contains a handle that identifies the but- 


ton control in its low-order word and the 
BN. DISABLE notification code in its 
high-order word. 


Comments 


This code applies only to buttons that have BS_ USERBUTTON style. 


BN DOUBLECLICKED 


This code specifies that the user has double-clicked a button. The control’s 
parent window receives this code through a WM_ COMMAND message 
from a button control. 


Parameter Description 
wParam Specifies the control ID. 
lParam Contains a handle that identifies the button 


control in its low-order word and the 
BN DOUBLECLICKED notification code 


in its high-order word. 


Comments 


This control applies only to buttons with BS. USERBUTTON and 
BS— RADIOBUTTON styles for 2.0 applications. 
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BN_ HILITE 


BN- HILITE 


This code specifies a request to highlight a button. The control’s parent 
window receives this code through a WM_ COMMAND message from a 
button control. 


Parameter Description 

wParam Contains the wParam parameter of the 
WM... COMMAND message, and specifies the 
control ID. 

lParam Contains a handle that identifies the button 


control in its low-order word and the 
EN. HILITE notification code in its high- 
order word. 


Comments 


This code applies only to buttons that have BS_ USERBUTTON style. 


BN. PAINT 


This code specifies a request to repaint a button. The control’s parent win- 
dow receives this code through a WM. COMMAND message from a button 
control. 


Parameter Description 

wParam Contains the wParam parameter of the 
WM_ COMMAND message, and specifies the 
control ID. 

lParam Contains a handle that identifies the button 


control in its low-order word and the BN. PAINT 


notification code in its high-order word. 


Comments 


This code applies only to buttons that have Bs_ USERBUTTON style. 
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BN_ UNHILITE 


This code specifies a request to remove highlighting from a button. The 
control’s parent window receives this code through a WM_ COMMAND 
message from a button control. 


Parameter Description 

wParam Contains the wParam parameter of the 
WM_ COMMAND message, and specifies the 
control ID. 

lParam Contains a handle that identifies the but- 


ton control in its low-order word and the 
BN_ UNHILITE notification code in its 
high-order word. 


Comments 


This code apphes only to buttons that have BS. USERBUTTON style. 
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DM_ GETDEFID 


DM_ GETDEFID 


This message retrieves the ID of the default push-button control for a 
dialog box. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


Return Value 


The return value is a 32-bit value. The high-order word contains 
DC_HASDEFID if the default button exists; otherwise, it is NULL. 
The low-order word contains the ID of the default button if the high- 
order word contains DC. HASDEFID; otherwise, it 1s zero. 


DM_ SETDEFID 


This message is used by an application to change the default push-button 


control ID for a dialog box. 


Parameter Description 

wParam Contains the ID of the new default push-button 
control. 

[Param Is not used. 
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EM_ CANUNDO 


This message determines whether an edit control can respond correctly to 


an EHM_ UNDO message. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


Return Value 


The return value is nonzero if the edit control can process the EM_ UNDO 
message correctly. Otherwise, it 1s zero. 


Comments 


The EM. CANUNDO message is implemented only for multiline edit 
controls. 


EM_FMTLINES 


This message directs the edit control to add or remove the end-of-line 
character from wordwrapped text lines. 


Parameter Description 

wParam Indicates the disposition of end-of-line characters. If the 
wParam parameter is nonzero, the characters CR CR LF 
(OD OD OA hexadecimal) are placed at the end of word- 
wrapped lines. If wParam is zero, the end-of-line char- 
acters are removed from the text. 


lParam Is not used. 


Return Value 


The return value is nonzero if any formatting occurs. Otherwise, it is zero. 
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EM_ FMTLINES 


Comments 

Lines that end with a hard return (a carriage return entered by the user) 
contain the characters CR LF at the end of the line. These lines are not 
affected by the EM_ FMTLINES message. 


Notice that the size of the text changes when this message is processed. 


EM_ GETHANDLE 


This message returns the data handle of the buffer that holds the contents 
of the control window. The handle is always a local handle to a location in 
the application’s data segment. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


Return Value 


The return value is a data handle that identifies the buffer that holds the 
contents of the edit control. 


Comments 
This message is not processed by single-line edit controls. If this message is 


used to obtain a handle that identifies an edit control in a dialog box, the 
dialog box must have been created with the DS_LOCALEDIT style. 


EM_ GETLINE 


This message copies a line from the edit control. 


Parameter Description 

wParam Specifies the line number of the line in the control, 
where the line number of the first line is zero. 

lParam Points to the buffer where the line will be stored. The 


first word of the buffer specifies the maximum number 
of bytes to be copied to the buffer. The copied line is 
not null-terminated. 
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Return Value 


The return value is the number of bytes actually copied. This message is 
not processed by single-line edit controls. 


EM_ GETLINECOUNT 


This message returns the number of lines of text in the edit control. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


Return Value 


The return value is the number of lines of text in the control. 


Comments 


This message is not processed by single-line edit controls. 


EM_~ GETMODIFY 


This message returns the current value of the modify flag for a given edit 
control. The flag is set by the control if the user enters or modifies text 
within the control. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


Return Value 


The return value is the value of the current modify flag for a given edit 
control. 
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BEM_ GETRECT 


This message retrieves the formatting rectangle of the control. 


Parameter Description 
wParam Is not used. 
(Param Points to a RECT data structure. The control copies 


the dimensions of the structure. 


EM_ GETSEL 


This message returns the starting and ending character positions of the 
current selection. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 
Return Value 


The return value is a long value that contains the starting position in the 
low-order word. It contains the position of the first nonselected character 
after the end of the selection in the high-order word. 


EM_ LIMITTEXT 


This message limits the length (in bytes) of the text the user may enter. 
Parameter Description 


wParam Specifies the maximum number of bytes that can be 
entered. If the user attempts to enter more characters, 
the edit control beeps and does not accept the char- 
acters. If the wParam parameter is zero, no limit ts 
imposed on the size of the text (until no more memory 
is available). 


lParam Is not used. 
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EM_ LINEENDE-X 


Comments 


The EM LIMITTEXT message does not affect text set by the 
WM. SETTEXT message or the buffer set by the EM_SETHANDLE 


message. 


EM_ LINEFROMCHAR 
This message returns the line number of the line that contains the charac- 


ter whose position (indexed from the beginning of the text) is specified by 
the wParam parameter. 


Parameter Description 
wParam Contains the index value for the desired character in 
the text of the edit control (these index values are zero- 


based), or contains —1. 


lParam Is not used. 


Return Value 


The return value is a line number. If wParam is -1, the number of the line 
that contains the first character of the selection is returned; otherwise, 
wParam contains the index (or position) of the desired character in the 
edit-control text, and the number of the line that contains that character 
is returned. 


EM LINEINDEX 


This message returns the number of character positions that occur preced- 
ing the first character in a given line. 


Parameter Description 

wParam Specifies the desired line number, where the line number 
of the first line is zero. If the wParam parameter is —1, 
the current line number (the line that contains the 
caret) is used. 


lParam Is not used. 
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EM_ LINEINDE-X 


Return Value 


The return value is the number of character positions that precede the 
first character in the line. 


Comments 


This message will not be processed by single-line edit controls. 


EM_LINELENGTH 


This message returns the length of a line (in bytes) in the edit control’s 
text buffer. 


Parameter Description 


wParam Specifies the character index of a character in the 
specified line, where the line number of the first line 
is zero. If the wParam parameter is —1, the length of 
the current line (the line that contains the caret) is 
returned, not including the length of any selected 
text. If the current selection spans more than one line, 
the total length of the lines, minus the length of the 
selected text, is returned. 


lParam Is not used. 


Comments 


Use the EM_. LINEINDEX message to retrieve a character index for a 
given line number. This index can be used with the EM_ LINELENGTH 


message. 
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EM_ SCROLL 


EM_ LINESCROLL 


This message scrolls the content of the control by the given number of 
lines. 


Parameter Description 
wParam Is not used. 
[Param Contains the number of lines and character positions to 


scroll. The high-order word of the [Param parameter 
contains the number of lines to scroll vertically; the 
low-order word contains the number of character posi- 
tions to scroll horizontally. 


Comments 


This message will not be processed by single-line edit controls. 


EM. REPLACESEL | 


This message replaces the current selection with new text. 


Parameter Description 

wParam Is not used. 

[Param Points to a null-terminated string of replacement text. 
EM_ SCROLL 


This message directs the edit control to scroll the contents of its window 
vertically. 


Parameter Description 
wParam Specifies one of the following values: 
Value Meaning 
EM. GETTHUMB Return the current thumb 
position. 
SB_ LINEDOWN Scroll one line down. 
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EM_ SCROLL 


SB_ LINEUP Scroll one line up. © 

SB_ PAGEDOWN Scroll one page down. 

SB_ PAGEUP Scroll one page up. 

SB. THUMBPOSITION — Scroll to thumb position. 
lParam Is not used. 


Return Value 


The return value is the current thumb position if the wParam parameter 


is EM_ GETTHUMB. 


Comments 


This message will not be processed by single-line edit controls. 


EM_SETHANDLE 


This message establishes the text buffer used to hold the contents of the 
control window. 


Parameter Description 


wParam Contains a handle to the buffer. The handle must be a 
local handle to a location in the application’s data seg- 
ment. The edit control uses this buffer to store the 
currently displayed text, instead of allocating its own 
buffer. If necessary, the control reallocates this buffer. 


lParam Is not used. 


Comments 
This message will not be processed by single-line edit controls. 


If the EM. SETHANDLE message is used to change the text buffer used by 
an edit control, the previous text buffer is not destroyed. The application 
must retrieve the previous buffer handle before setting the new handle, 
and must free the old handle by using the LocalF ree function. 


An edit control automatically reallocates the given buffer whenever it 
needs additional space for text, or it removes enough text so that addi- 
tional space is no longer needed. If this message is used to set a handle 
that identifies an edit control in a dialog box, the dialog box must have 
been created with LOCALEDIT style. 
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EM_ SETMODIFY 


This message sets the modify flag for a given edit control. 


Parameter Description 

wParam Specifies the new value for the modify flag. 
lParam Is not used. 

EM_ SETRECT 


This message sets the formatting rectangle for a control. The text is 
reformatted and redisplayed to reflect the changed rectangle. 


Parameter _ Description 
wParam Is not used. 
[Param Points to a RECT data structure that specifies the new 


dimensions of the rectangle. 


Comments 


This message will not be processed by single line-edit controls. 


EM_ SETRECTNP 


This message sets the formatting rectangle for a control. The text is 
reformatted and redisplayed to reflect the changed rectangle. The 
EM_SETRECTNP message is the same as the EM_SETRECT message, 
except that the control is not repainted. Any subsequent alterations cause 
the control to be repainted to reflect the changed formatting rectangle. 
This message is used when the field is to be repainted later. 


Parameter Description 
wParam Is not used. 
lParam | Points to a RECT data structure that specifies the new 


dimensions of the rectangle. 
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EM_SETRECTNP 


Comments 


This message will not be processed by single-line edit controls. 


EM_SETSEL 


This message selects all characters in the current text that are within the 
starting and ending character positions given by the /Param parameter. 


Parameter Description 
wParam Is not used. 
(Param Specifies the starting position in the low-order word and 


the ending position in the high-order word. The position 
values 0 to 32767 select the entire string. 


EM_SETWORDBREAK 


This message is sent to the multiline edit control, informing the edit con- 
trol that Windows has replaced the default word-break function with an 
application-supplied word-break function. A word-break function scans a 
text buffer (which contains text to be sent to the display), looking for the 
first word that will not fit on the current display line. The word-break 
function places this word at the beginning of the next line on the display. 
A word-break function defines at what point Windows should break a 
line of text for multiline edit controls, usually at a blank character that 
separates two words. The default word-break function breaks a line of 
text at a blank character. The application-supplied function may define a 
word break to be a hyphen or character other than the blank character. 


Parameter Description 
wParam Is not used. 
lParam Is a procedure-instance address. 
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Comments 


The callback function must use the Pascal calling convention and must be 
declared FAR. The function must have the following form: 


LPSTR FAR PASCAL WordBreakFunc(lpchEditTeat, ichCurrent Word, cchEdit Text) 
LPSTR lpchEditTeats 

short ichCurrent Word; 

short cchEdit Text; 


WordBreakF unc is a placeholder for the application-supplied function 
name. The actual name must be exported by including it in an 
EXPORTS statement in the application’s module-definition file. 


Parameter Description 


lochEditTezt Points to the text of the edit control. 


ichCurrentWord Specifies an index to a word in the buffer of text 
that identifies at what point the function should 
begin checking for a word break. 


echEdit Text Specifies the number of bytes of edit text. 


Return Value 


The return value points to the first byte of the next word in the edit- 
control text. If the current word is the last word in the text, the return 
value points to the first byte that follows the last word. 


EKM_~ UNDO 


This message undoes the last edit to the edit control. When the user 
modifies the edit control, the last change is stored in an undo buffer, 
which grows dynamically as required. If insufficient space is available for 
the buffer, the undo attempt fails and the edit control is unchanged. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
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Return Value 


The return value is nonzero if the undo operation is successful. It is zero if 
the undo operation fails. 


Comments 


The EM_ UNDO message is implemented only for multiline edit controls. 


EN_ CHANGE 


This code specifies that the user has taken an action that may have 
altered text. It is sent after Windows updates a display (unlike the 
EN_ UPDATE code). The control’s parent window receives this code 
through a WM_ COMMAND message from the control. 


Parameter Description 


wParam Contains the wParam parameter of the 
WM_ COMMAND message, and specifies the 
contro] ID. 


[Param Contains an edit-control window handle in its 
low-order word and the EN. CHANGE code 


in its high-order word. 


EN_ ERRSPACE 


This code specifies that the edit control is out of space. The control’s 
parent window receives this code through a WM—~ COMMAND message 
from the control. 


Parameter Description 


wParam Contains the wParam parameter of the 


WM... COMMAND message, and specifies the 
control ID. 


lParam Contains an edit-control window handle in its 
low-order word and the EN. ERRSPACE code 


in its high-order word. — 
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EN- HSCROLL 


This code specifies that the user has clicked the edit control’s horizontal 
scroll bar. The control’s parent window receives this code through a 
WM_ COMMAND message from the control. The parent window is 
notified before the screen is updated. 


Parameter Description 

wParam Contains the wParam parameter of the 
WM_ COMMAND message, and specifies the 
control ID. 

lParam Contains an edit-control window handle in its 


low-order word and the EN. HSCROLL code 
in its high-order word. 


EN KILLFOCUS 


This code specifies that the edit control has lost the input focus. The 
control’s parent window receives this code through a WM_ COMMAND 
message from the control. 


Parameter Description 
wParam Contains the wParam parameter of the 
COMMAND message, and specifies the 
control ID. 
[Param Contains an edit-control window handle in its 


low-order word and the EN. KILLFOCUS code 
in its high-order word. 


EN_SETFOCUS 


This code specifies that the edit control has obtained the input focus. The 
control’s parent window receives this code through a WM_ COMMAND 
message from the control. 
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Parameter Description 

wParam Contains the wParam parameter of the 
WM_ COMMAND message, and specifies the 
control ID. 

[Param Contains an edit-control window handle in its 


low-order word and the EN_SETFOCUS code 
in its high-order word. 


EN_ UPDATE 


The code specifies that the edit control will display altered text. The 
control’s parent window receives this code through a WM_ COMMAND 
message from the control; notification occurs after the control has format- 
ted the text, but before it displays the text. This makes it possible to alter 
the window size, if necessary. 


Parameter Description 
wParam Specifies the control ID. 
lParam Contains an edit-control window handle in its 


low-order word and the EN. UPDATE code in 
its high-order word. 


EN_- VSCROLL 


This code specifies that the user has clicked the edit control’s vertical 
scroll bar. The control’s parent window receives this code through a 
WM_ COMMAND message from the control; notification occurs before 
the screen is updated. 


Parameter Description 

wParam Contains the wParam parameter of the 
WM. COMMAND message, and specifies the- 
control ID. 

lParam Contains an edit-control window handle in its 


low-order word and the EN. VSCROLL code 
in its high-order word. 


540 


Nhe eae 


LB_ DIR 


LB_ADDSTRING 

This message adds a string to the list box. If the list box is not sorted, the 
string is added to the end of the list. If the list box is sorted, the string is 
inserted into the list after sorting. 


This message removes any existing list-box selections. 


Parameter Description 
wParam Is not used. 
lParam Points to the null-terminated string that is to be added. 


Return Value 
The return value is the index to the string in the list box. The LB_ ERR 


message is returned if an error occurs; the LB-ERRSPACE message is 
returned if insufficient space is available to store the new string. 


LB_DELETESTRING 


This message deletes a string from the list box. 


Parameter Description 
wParam Contains an index to the string that is to be deleted. 
[Param Is not used. 


Return Value 


The return value is a count of the strings remaining in the list. The 
LB. ERR message is returned if an error occurs. 


LB_ DIR 


This message adds a list of the files from the current directory to the list 
box. Only files with the attributes specified by the wParam parameter and 
that match the file specification given by the [Param parameter are added. 
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Parameter Description 


wParam Contains a DOS attribute value. For a list of the DOS 
attributes, see the DlgDirList function in Chapter 3, 
“Functions Directory.” 


[Param Points to a file-specification string. The string can con- 
tain wildcard characters (for example, *.*). 


Return Value 
The return value is a count of items displayed. The LB_ ERR message is 


returned if an error occurs; the LB-ERRSPACE message is returned if 
insufficient space is available to store the new strings. 


Comments 


The return value of the LB. DIR message is one less than the return value 
of the LB_ GETCOUNT message. 


LB_ GETCOUNT 


This message returns a count of the items in the list box. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 


Return Value 


The return value is a count of the items in the list box. The LB_ERR 
message is returned if an error occurs. 


LB_ GETCURSEL 


This message returns the index of the currently selected item, if any. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
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LB. GETTEXT 


Return Value 
The return value is the index of the currently selected item. It is the 


LB_ERR message if no item is selected or if the list-box type is multiple 
selection. 


LB. GETSEL 


This message returns the selection state of an item. 


Parameter Description 

wParam Contains an index to the item. 
lParam Is not used. 

Return Value 


The return value is a positive number if an item is selected. Otherwise, it 
is zero. The LB_ ERR message is returned if an error occurs. 


LB_ GETTEXT 


This message copies a string from the list into a buffer. 


Parameter Description 
wParam Contains the index of the string to be copied. 
lParam Points to the buffer that is to receive the string. The 


buffer must have both sufficient space for the string and 
a terminating null character. 


Return Value 


The return value is the length of the string (in bytes), excluding the termi- 
nating null character. The LB- ERR message is returned if the wParam 
parameter is not a valid index. 
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LB_ GETTEXTLEN 


This message returns the length of a string in the list box. 


Parameter Description 
wParam Contains an index to the string. 
lParam Is not used. 


Return Value 
The return value is the length of the string (in bytes), excluding the ter- 


minating null character. The LB. ERR message is returned if an error 
occurs. 


LB_INSERTSTRING 


This message inserts a string into the list box. No sorting is performed. 
Parameter Description 


wParam Contains an index to the position that will receive the 
string. If the wParam parameter is —1, the string 1s 
added to the end of the list. 


[Param Points to the string. 


Return Value 


The return value is the index of the position at which the string was 
inserted. The LB_ ERR message is returned if an error occurs; the 
LB. ERRSPACE message is returned if insufficient space is available 
to store the new string. 


LB_RESETCONTENT 


This message removes all strings from a list box and frees any memory 
allocated for those strings. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
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LB_SELECTSTRING 


This message changes the current selection to the first string that has the 
specified prefix. 


Parameter Description 


wParam Contains the index of the starting point for the search. 
The starting point is not included in the search, so the 
value returned by the LB- GETCURSEL message can be 
used as the starting point. If the wParam parameter is 
—1, the string 1s searched from the beginning. 


lParam Points to the prefix string. The string must have a null 
terminating character. | 


Return Value 


The return value is the index of the selected item. The LB- ERR message 
is returned if an error occurs. 


Comments 


This message must not be used with list boxes that are multiple-selection 
type. 


A string is selected only if its initial characters (from the starting point) 
match the characters in the prefix string. 


LB_SETCURSEL 


This message selects a string and scrolls it into view, if necessary. When 
the new string is selected, the list box removes the highlight from the 
previously selected string. 


Parameter Description 
wParam Contains the index of the string that is selected. 
[Param Is not used. 
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Return Value 


The return value is the LB-ERR message if an error occurs. 


Comments 


This message should be used only with single-selection list boxes. It cannot 
be used to set or remove a selection in a multiple-selection list box. 


LB_SETSEL 


This message selects a string in a multiple-selection list box. 
Parameter Description 
wParam Specifies how to set the selection. If the wParam param- 


eter is nonzero, the string is highlighted; if wParam is 
zero, any darkened effect is removed. 


[Param The low-order word of the [Param parameter is an index 
that specifies which string to set. If (Param is —-1, the 
selection is removed from all strings. 


Return Value 
The return value is the LB_ERR message if an error occurs. 
Comments 


This message should be used only with multiple-selection list boxes. 


LBN_ DBLCLK 
This code specifies that the user has double-clicked a string. The control’s 


parent window receives this code through a WM— COMMAND message 
from the control. 
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LBN_ SELCHANGE 


Parameter Description 

wParam Contains the wParam parameter of the 
WM_ COMMAND message, and specifies the 
control ID. 

lParam Contains an edit-control window handle in its 


low-order word and the LBN. DBLCLK code 
in its high-order word. 


Comments 


This code applies only to list-box controls that have LBS_ NOTIFY style. 


LBN- ERRSPACE 


This code specifies that the list-box control cannot allocate enough mem- 
ory to meet a specific request. The control’s parent window receives this 
code through a WM COMMAND message from the control. 


Parameter Description 

wParam Contains the wParam parameter of the 
WM_ COMMAND message, and specifies the 
control ID. 

[Param Contains an edit-control window handle in its 


low-order word and the LBN_ ERRSPACE code 
in its high-order word. 


Comments 


This code applies only to list-box controls that have LBS_ NOTIFY style. 


LBN_- SELCHANGE 
This code specifies that the selection changed. The control’s parent win- 


dow receives this code through a WM. COMMAND message from the 


control. 
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LBN_ SELCHANGE 


Parameter Description 
wParam Contains the wParam parameter of the 
WM_ COMMAND message, and specifies the 
control ID. 
[Param Contains an edit-control window handle in its _ 


low-order word and the LBN. SELCHANGE code 


in its high-order word. 


Comments 


This code applies only to list-box controls that have LBS_ NOTIFY style. 
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WM_ACTIVATE 


This message is sent when a window becomes active or inactive. 


Parameter 


wParam 


[Param 


Default Action 


Description 


Specifies the new state of the window. The wParam 
parameter is zero if the window is inactive; it is one of 
the following nonzero values if the window is being 
activated: 


Value Meaning 


1 The window is being activated through 
some method other than a mouse click 
for example, through a call to the 
etActive Window function or selection 
of the window by the user through the 
keyboard interface). 


2 The window is being activated by a 
mouse click by the user. Any mouse but- 
ton can be clicked: right, left, or middle. 


Specifies the high-order word of the [Param parameter. 
The high-order word of the [Param parameter is nonzero 
if the window is iconic. Otherwise, it is zero. The value 
of the low-order word of [Param depends on the value of 
the wParam parameter. If wParam is zero, the low- 
order word of [Param is a handle to the window being 
activated. If wParam is nonzero, the low-order word of 
(Param is the handle of the window being inactivated 


(this handle may be NULL). 


If the window is being activated and is not iconic, the DefWindowProc 
function sets the input focus to the window. 
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WM_ACTIVATEAPP 


This message is sent when a window being activated belongs to a different 
application than the currently active window. The message is sent to the 
application whose window will be activated and the application whose 


window will be deactivated. er 
Parameter Description 
wParam Specifies whether a window is being activated or deac- 


tivated. A nonzero value indicates that Windows will 
activate a window; zero indicates that Windows will 
deactivate a window. 


lParam Contains the task handle of the application. If the 
wParam parameter is nonzero, the low-order word of the 
[Param parameter contains the task handle of the appli- 
cation that owns the window that is being activated. If 
wParam is zero, the low-order word of [Param contains 
the task handle of the application that owns the window 
that is being deactivated. 


WM. ASKCBFORMATNAME 


This message is sent when the clipboard contains a data handle for the 
CF... OWNERDISPLAY format (that is, the clipboard owner should display 
the clipboard contents), and requests a copy of the format name. 


Parameter Description 
wParam Specifies the maximum number of bytes to copy. 
[Param Points to the buffer where the copy of the format name 


is to be stored. 


Comments 


The clipboard owner should copy the name of the CF_ OWNERDISPLAY 
format into the specified buffer, not exceeding the maximum number of 
bytes. 
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WM_ CANCELMODE 


This message cancels any mode the system is in, such as one that 
tracks the mouse in a scroll bar or moves a window. Windows sends 
the WM. CANCELMODE message when an application displays a 


message box. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 
WM. CHANGECBCHAIN 


This message notifies the first window in the clipboard-viewer chain that a 
window is being removed from the chain. 


Parameter Description 


wParam Contains the handle to the window that is being 
removed from the clipboard-viewer chain. 


lParam Contains in its low-order word the handle to the win- 
dow that follows the window being removed from the 
clipboard-viewer chain. 


Comments 


Each window that receives the WM. CHANGECBCHAIN message should 
call the SendMessage function to pass on the message to the next win- 
dow in the clipboard-viewer chain. If the window being removed is the 
next window in the chain, the window specified by the low-order word of 
the [Param parameter becomes the next window, and clipboard messages 
are passed on to it. 


WM. CHAR 
This message results when a WM_KEYUP and a WM_KEYDOWN 


message are translated. It contains the value of the keyboard key being 
pressed or released. 
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Parameter Description 
wParam Contains the value of the key. 
[Param Contains the repeat count, scan code, key-transition 


code, previous key state, and context code, as shown in 
the following list. In this list, bit 1 is the low-order bit: 


Bit Value 
0-15 Repeat count (the number of times the key- 


stroke is repeated as a result of the user 
holding down the key). 


16-23 Scan code (OEM-dependent value). 

24-28 Not used. 

29 Context code (1 if the ALT key is held down 
while the key is pressed, 0 otherwise). 

30 Previous key state (1 if the key is down 
before the message is sent, 0 if the key 1s 
up). 

31 . Transition state : if the key is being 
released, O if the key is being pressed). 


Comments 


Since there is not necessarily a one-to-one correspondence between keys 
pressed and character messages generated, the information in the high- 
order word of the lParam parameter is generally not useful to applications. 
The information in the high-order word applies only to the most recent 
WM_ KEYUP or WM_KEYDOWN message that precedes the posting of 
the character message. 


WM_ CHILDACTIVATE 


This message is sent to a child window’s parent window when the 
Set WindowPos function moves a child window. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
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WM_ CLEAR 


This message deletes the current selection. 


Parameter Description 
wParam Is not used. 
lParam Js not used. 
WM_ CLOSE 


This message occurs when a window is closed. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 
Default Action 


WM_ COMMAND 


The DefWindowProc function calls the Destroy Window function to 


destroy the window. 


Comments 


An application can prompt the user for confirmation, prior to destroy- 
ing a window, by processing the WM_ CLOSE message and calling the 
Destroy Window function only if the user confirms the choice. 


WM... COMMAND 


This message occurs when the user selects an item from a menu, when a 
control passes a message to its parent window, or when an accelerator 


keystroke is translated. 
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WM_ COMMAND 


Parameter Description 
wParam Contains the menu item, the control ID, or the accel- 
erator ID. 
[Param Specifies whether the message is from a menu, an om 


accelerator, or a control. The low-order word contains 
zero if the message is from a menu. The high-order word 
contains | if the message is an accelerator message. If 
the message is from a control, the high-order word of the 
[Param parameter contains the notification code. The 
low-order word is the window handle of the control 
sending the message. 


Comments 


Accelerator keystrokes that are defined to select items from the system 
menu are translated into WM. SYSCOMMAND messages. 


If an accelerator keystroke that corresponds to a menu item occurs when 
the window that owns the menu is iconic, no WMW— COMMAND message 
is sent. However, if an accelerator keystroke that does not match any 

of the items on the window’s menu or on the System menu occurs, a 


WM. COMMAND message is sent, even if the window is iconic. 


WML_ COPY 


This message sends the current selection to the clipboard in CF_ TEXT 
format. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
WM. CREATE 


This message informs the window procedure that it can perform any inl- 
tialization. The Create Window function sends this message before it 
returns and before the window is opened. er 
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WM_ CTLCOLOR 


Parameter Description 
wParam Is not used. 
lParam Points toa CREATESTRUCT data structure 


that contains copies of parameters passed to the 
Create Window function. 


WM. CTLCOLOR 


This message is sent to the parent window of a predefined control or 
message box when the control or message box is about to be drawn. By 
responding to this message, the parent window can set the text and back- 
ground colors of the child window by using the display-context handle 
given in the wParam parameter. 


Parameter Description 

wParam Contains a handle to the display context for the child 
window. 

lParam The low-order word of the lParam parameter identifies 


the child window. The high-order word is one of the fol- 
lowing values, specifying the type of control: 


Value Control Type 
CTLCOLOR_ BTN Button control 7 
CTLCOLOR_ DLG Dialog box 
CTLCOLOR_ EDIT Edit control 


CTLCOLOR-LISTBOX _List-box control 
CTLCOLOR— MSGBOX Message box 
CTLCOLOR- SCROLLBAR. Scroll-bar control 
CTLCOLOR_ STATIC Static control 


Default Action 


The DefWindowProc function selects the default system colors. 
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WM_ CTLCOLOR 
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If an application processes the WM. CTLCOLOR message, it must return 
a handle to the brush that is to be used for painting the control back- 
ground. Note that failure to return a valid brush handle will place the 
system in an unstable state. 


WM_CUT 


This message sends the current selection to the clipboard in CF_ TEXT 
format, and then deletes the selection from the control window. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 
WM_DEADCHAR 


This message results when a WM_KEYUP and a WM_KEYDOWN mes- 
sage are translated. It specifies the character value of a dead key. A dead 
key is a key, such as the umlaut (double-dot) character, that is combined 
with other characters to form a composite character. For example, the 
umlaut-O character consists of the dead key, umlaut, and the O key. 


Parameter Description 
wParam Contains the dead-key character value. 
[Param Contains the repeat count, scan code, key-transition 


code, previous key state, and context code, as shown in 
the following list. In this list, bit 1 1s the low-order bit: 


Bit Value 
0-15 Repeat count (the number of times the key- 


stroke is repeated as a result of the user 
holding down the key). 


16-23 Scan code (OEM-dependent value). 
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WM_ DESTROY 


24-28 Not used. 

29 Context code (1 if the ALT key is held down 
while the key is pressed, 0 otherwise). 

30 Previous key state (1 if the key is down 
before the message is sent, 0 if the key 
is up). 

31 Transition state : if the key is being 
released, 0 if the key is being pressed). 


Comments 


The WM DEADCHAR message typically is used by applications to give 
the user feedback about each key pressed. 


Since there is not necessarily a one-to-one correspondence between keys 
pressed and character messages generated, the information in the high- 
order word of the [Param parameter is generally not useful to applications. 
The information in the high-order word applies only to the most recent 
WM_ KEYUP or WM_KEYDOWN message that precedes the posting of 


the character message. 


WM_ DESTROY 


This message informs the window that it is being destroyed. The 

Destroy Window function sends the WM_ DESTROY message to the 
window after removing the window from the screen. The WM_ DESTROY 
message is sent to a parent window before any of its child windows are 
destroyed. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
Comments 


If the window being destroyed is part of the clipboard-viewer chain 
(set by using the SetClipboard Viewer function), the window must 
remove itself from the clipboard viewer chain by processing the 
ChangeClipboardChain function before returning from the 

WM... DESTROY message. 
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WM_ DESTROYCLIPBOARD 


WM_ DESTROYCLIPBOARD 


This message is sent to the clipboard owner when the clipboard is emptied 
through a call to the EmptyClipboard function. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 
WM_ DEVMODECHANGE 


This message is sent to all top-level windows when the user changes 
device-mode settings. 


Parameter Description 
wParam Is not used. 
lParam Points to the device name specified in the Windows 


initialization file, win.enz. 


WM_~ DRAWCLIPBOARD 


This message is sent to the first window in the clipboard-viewer chain 
when the contents of the clipboard change. Only applications that have 
joined the clipboard-viewer chain by calling the SetClipboard Viewer 
function need to process this message. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
Comments 


Each window that receives the WM_ DRAWCLIPBOARD message should 
call the SendMessage function to pass the message on to the next win- 
dow in the clipboard-viewer chain. The handle of the next window is 
returned by the SetClipboard Viewer function; it may be modified in 
response to a WM. CHANGECBCHAIN message. 
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WM_ERASEBKGND 


WM_ ENABLE 

This message is sent after a window has been enabled or disabled. 
Parameter Description 

wParam Specifies whether the window has been enabled or dis- 


abled. The wParam parameter is nonzero if the window 
has been enabled; it is zero if the window has been dis- 


abled. 
[Param Is not used. 
WM_ENDSESSION 


‘This message is sent to tell an application that has responded nonzero to a 
br aac anc message whether the session is actually being 
ended. | 


Parameter Description 

wParam Specifies whether or not the session is being ended. It is 
nonzero if the session is being ended. Otherwise, it is 
ZeTO. 

[Param Is not used. 

Comments 


The application does not need to call the Destroy Window or 
Post QuitMessage function when the session is being ended. 


WM_ ERASEBKGND 


This message is sent when the window background needs erasing (for 
example, when a window is resized). [t is sent to prepare an invalidated 
region for painting. 


Parameter Description 
wParam Contains the device-context handle. 
lParam Is not used, 
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WM_ ERASEBKGND 


Return Value 


The return value is nonzero if the background is erased. Otherwise, it is 
zero. If the application processes the WM_ERASEBKGND message, it 
should return the appropriate value. 


Default Action 


The background is erased, using the class background brush specified by 
the hbrbackground field in the class structure. 


Comments 


If hbrbackground is NULL, the application should process the 
WM... ERASEBKGND message and erase the background color. When 
processing the WM_ ERASEBKGND message, the application must 
align the origin of the intended brush with the window coordinates by 
first calling the UnrealizeObject function for the brush, and then 
selecting the brush. 


Windows assumes the background should be computed by using the 
MM_ TEXT mapping mode. If the device context is using any other 
mapping mode, the area erased may not be within the visible part of 
the client area. 


WM_FONTCHANGE 


This message occurs when the pool of font resources changes. Any applica- 
tion that adds or removes fonts from the system (for example, through the 
AddFontResource or RemoveFontResource function) should send 
this message to all top-level windows. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
Comments 


To send the WM_ FONTCHANGE message to all top-level windows, an 
application can call the SendMessage function with the hWnd parameter 


set to FFFF (hexadecimal). 
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WM_ GETDLGCODE 


WM_ GETDLGCODE 


This message is sent by the Windows dialog manager to an input pro- 
cedure associated with a control. Normally, the dialog manager handles 
all arrow-key and TAB-key input to the control. By responding to the 
WM_ GETDLGCODE message, an application can take control of a par- 


ticular type of input and process the input itself. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
Return Value 


The return value is one or more of the following values, indicating which 
type of input the application processes: 


DLGC. DEFPUSHBUTTON — Default push button 


DLGC_ HASSETSEL EM_ SETSEL messages 
DLGC_ PUSHBUTTON Push button 

DLGC_ RADIOBUTTON Radio button 

DLGC_ WANTALLKEYS All keyboard input 
DLGC_ WANTARROWS DIRECTION keys 
DLGC_ WANTCHARS WM_ CHAR messages 


DLGC_ WANTMESSAGE All keyboard. input (the application 


passes.this message on to control) 


DLGC.. WANTTAB TAB key 


Default Action 


The DefWindowProc function returns zero. 


Comments 


Although the DefWindowProc function always returns zero in response 
to the WM_ GETDLGCODE message, the window functions for the pre- 


defined control classes return a code appropriate for each class. 


The WM_ GETDLGCODE message and the returned values are useful 
only with user-defined dialog controls or standard controls modified by 
subclassing. 
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WM_ GETMINMAXINE'O 


WM_ GETMINMAXINFO 


This message is sent to a window whenever Windows needs to know the 
maximized size of the window, the minimum or maximum tracking size of 
the window, or the maximized position of the window. The maximized size 
of a window is the size of a window when its borders are fully extended. 
The maximum tracking size of a window is the largest window size that 
can be achieved by using the borders to size the window. The minimum 
tracking size of a window is the smallest window size that can be achieved 
by using the borders to size the window. 


Parameter 


wParam 


lParam 
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Description 


Is not used. 


Points to an array of five points that contains the fol- 
lowing information: 


Point 


rgpt/0] 
rgpt/1 


rgpt/2/ 


rgpt/$] 


rgpt/4] 


Description 


Used internally by Windows. 


The maximized size, which is the screen 

size by default. The width is 

SM_ CXSCREEN + (2 x SM. CXFRAME)). 
he height is 

(SM_ CYSCREEN + (2 X SM_CYFRAMEB)). 


The maximized position of the upper- 
left corner of the window (in screen 
coordinates). The default z value is 
SM..CXFRAME. The default y value 
is SM_.CYFRAME. 


The minimum tracking size, which is 
the iconic size by default. The width is 
SM_ CXMINTRACK. The height 

is SM_ CYMINTRACK. 


The maximum tracking size, which is 

less than the screen size by default. 

The width is 

SM_ CXSCREEN + (2 x SM_ CXFRAME)). 
he height is 

(SM_ CYSCREEN + (2 XK SM. CYFRAME)). 


WM_ GETTEXTLENGTH 


Comments 


The array contains default values for each point before Windows sends the 
WM_ GETMINMAXINFO message. This message gives the application the 
opportunity to alter the default values. 


WM_GETTEXT 


This message is used to copy the text that corresponds to a window. For 
edit controls, the text to be copied is the content of the control. For but- 
ton controls, the text is the button name. For other windows, the text is 
the window caption. 


Parameter Description 

wParam Specifies the maximum number of bytes to be copied, 
including the null terminating character. 

lParam Points to the buffer that is to receive the text. 

Comments 


The return value is the number of bytes copied. 


WM_ GETTEXTLENGTH 


This message is used to find the length tin bytes) of the text associated 
with a window. The length does not include the null terminating charac- 
ter. For edit controls, the text is the content of the control. For button 
controls, the text is the button name. For other windows, the text is the 
window caption. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
Comments 


The return value is the length of the given text. 
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WM_ HSCROLL 


WM_HSCROLL 


This message is sent when the user clicks the horizontal scroll bar. 


Parameter 


wParam 


lParam | 


Comments 


Description 


Contains a scroll-bar code that specifies the user’s scroll- 
ing request. It can be any one of the following values: 


Value 


SB_ BOTTOM 

SB_ ENDSCROLL 

SB_ LINEDOWN 

SB_ LINEUP 

SB_ PAGEDOWN 

SB.. PAGEUP 

SB. THUMBPOSITION 
SB_ THUMBTRACK 


SB_ TOP 


Meaning 


Scroll to lower right. 

End scroll. 

Scroll one line down. 
Scroll one line up. 

Scroll one page down. 
Scroll one page up. 

Scroll to absolute position. 


Drag thumb to specified 
position. 


Scroll to upper left. 


Specifies the window handle of the control. If the mes- 
sage is sent by a scroll-bar control, the high-order word 
of the [Param parameter contains the window handle of 
the control. If the message is sent as a result of the user 
clicking a pop-up window’s scroll bar, the high-order 


word is not used. 


The SB_ THUMBTRACK message typically is used by applications that 
give some feedback while the thumb ts being dragged. 


If an application scrolls the document in the window, it must also reset 
the position of the thumb by using the SetScrollPos function. 
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WM_INITDIALOG 


WM_ HSCROLLCLIPBOARD 


This message is sent when the clipboard contains a data handle for the 
CF_OWNERDISPLAY format (that is, the clipboard owner should display 
the clipboard contents) and an event occurs in the clipboard application’s 
horizontal scroll bar. 


Parameter Description 
wParam Contains a handle to the clipboard application window. 
lParam Contains one of the following scroll-bar codes in the 


low-order word: 


Code Meaning 

SB. BOTTOM Scroll to lower right. 

SB. ENDSCROLL End scroll. 

SB. LINEDOWN Scroll one line down. 

SB_ LINEUP Scroll one line up. 
SB..PAGEDOWN Scroll one page down. 

SB. PAGEUP Scroll one page up. 

SB_ 'THUMBPOSITION Scroll to absolute position. 
SB_ TOP Scroll to upper left. 


The high-order word of the [Param parameter con- 
tains the thumb position if the scroll-bar code is 
SB..THUMBPOSITION,. Otherwise, the high-order 


word is not used. 


Comments 


The clipboard owner should use the InvalidateRect function or repaint 
as desired. The scroll-bar position should also be reset. 


WM_INITDIALOG 
This message is sent immediately before a dialog box is displayed. By pro- 


cessing this message, an application can perform any initialization before 
the dialog box is made visible. 
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WM_INITDIALOG 


Parameter Description 


wParam Identifies the first control item in the dialog box that 
can be given the input focus. Generally, this is the first 
item in the dialog box with WS. TABSTOP style. 


lParam Is not used. 


Comments 


If the application returns a nonzero value in response to the 
WML_INITDIALOG message, Windows sets the input focus to 
the item identified by the handle in the wParam parameter. The 
application can return only FALSE if it has set the input focus 
to one of the controls of the dialog box. 


WM_INITMENU 


This message is a request to initialize a menu. It occurs when a user moves 
the mouse into a menu bar and clicks, or presses a menu key. Windows 
sends this message before displaying the menu. This allows the application 
to change the state of menu items before the menu is shown. 


Parameter Description 

wParam Contains the menu handle of the menu that is to be 
initialized. 

[Param Is not used. 

Comments 


A WM_INITMENU message is sent only when a menu is first accessed; 
only one WM_INITMENU message is generated for each access. This 
means, for example, that moving the mouse across several menu items 
while holding down the button does not generate new messages. This 
message does not provide information about menu items. 


WM_INITMENUPOPUP 


This message is sent immediately before a pop-up menu is displayed. Pro- 
cessing this message allows an application to change the state of items on 
the pop-up menu before the menu is shown, without changing the state 
of the entire menu. 
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WM_KEYDOWN 


Parameter Description 

wParam Contains the menu handle of the pop-up menu. 

lParam Specifies the index of the pop-up menu. The low-order | 
word contains the index of the pop-up menu in the main 
menu. The high-order word is nonzero if the pop-up 
menu is the system menu. Otherwise, it is zero. 

WM_KEYDOWN 


This message is sent when a nonsystem key is pressed. A nonsystem key is 
a keyboard key that is pressed when the ALT key is not pressed, or a key- 
board key that is pressed when a window has the input focus. 


Parameter 


wParam 


lParam 


Description 


Specifies the virtual keycode of the given key. 


Contains the repeat count, scan code, key-transition 
code, previous key state, and context code, as shown in 
the following list. In this list, bit 1 is the low-order bit: 


Bit Value 
0-15 Repeat count (the number of times the key- 


stroke is repeated as a result of the user 
holding down the key). 


16-23 Scan code (OEM-dependent value). 

24-28 Not used. 

29 Context code (1 if the ALT key is held down 
while the key is pressed, 0 otherwise). 

30 Previous key state (1 if the key is down 
before the message is sent, 0 if the key 
is up). 

31 Transition state (1 if the key is being 


released, 0 if the key is being pressed). 


For WM_KEYDOWN messages, the key-transition bit 
(bit 31) is O and the context-code bit (bit 29) is 0. 
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WM_KEYDOWN 


Comments 


Because of auto-repeat, more than one WM_KEYDOWN message may 
occur before a WM. KEYUP message is sent. The previous key state 


(bit 30) can be used to determine whether the WM_KEYDOWN message 


indicates the first down transition or a repeated down transition. 


WM_ KEYUP 


This message is sent when a nonsystem key is released. A nonsystem key 1s 
a keyboard key that is pressed when the ALT key is not pressed, or a key- 
board key that is pressed when a window has the input focus. 


Parameter Description 
wParam Specifies the virtual keycode of the given key. 
lParam Contains the repeat count, scan code, key-transition 


code, previous key state, and context code, as shown in 
the following list. In this list, bit 1 is the low-order bit: 


‘Bit Value 
0-15 Repeat count (the number of times the key- 


stroke is repeated as a result of the user 
holding down the key). 


16-23 Scan code (OEM-dependent value). 

24-28 Not used. 

29 Context code (1 if the ALT key is held down 
while the key is pressed, 0 otherwise). 

30 Previous key state (1 if the key is down 
before the message is sent, 0 if the key 
is up). 

31 Transition state (1 if the key is being 


released, 0 if the key is being pressed). 


For WM_KEYUP messages, the key- 
transition bit (bit 31) is 1 and the context- 
code bit (bit 29) is 0. 
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WM_LBUTTONDBLCLK 


WM_KILLFOCUS 
This message is sent immediately before a window loses the input focus. 
Parameter Description 


wParam Contains the handle of the window that receives the 
input focus (may be NULL). 


[Param Is not used. 


Comments 


If an application is displaying a caret, the caret should be destroyed at 
this point. 


WM_LBUTTONDBLCLK 


This message occurs when the user double-clicks the left mouse button. 


Parameter Description 

wParam Contains a value that indicates whether various virtual 
keys are down. It can be any combination of the follow- 
ing values: 
Value | Meaning 


MK_~ CONTROL _ Set if CONTROL key is down. 
MK_LBUTTON _ Set if left button is down. 
MK_MBUTTON _ Set if middle button is down. 
MK_RBUTTON _ Set if right button 1s down. 
Mk_ SHIFT Set if SHIFT key is down. 


lParam Contains the # and ycoordinates of the mouse cur- 
sor. The z-coordinate 1s in the low-order word; the 
y-coordinate is in the high-order word. These coor- 
dinates are always relative to the upper-left corner 
of the window. 
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WM_LBUTTONDBLCLK 


Comments 


Only windows whose window class has CS DBLCLKS style can receive 
double-click messages. Windows generates a double-click message when 
the user presses, releases, and then presses a mouse button again within 
the system’s double-click time limit. Double-clicking actually generates 
four messages: a down-click message, an up-click message, the double- 
click message, and another up-click message. 


WM_LBUTTONDOWN 


This message occurs when the user presses the left mouse button. 


Parameter Description 

wParam Contains a value that indicates whether various virtual 
keys are down. It can be any combination of the follow- 
ing values: 
Value Meaning 


MK..CONTROL — Set if CONTROL key is down. 
MK~ MBUTTON | Set if middle button is down. 
MK. RBUTTON _ Set if right button is down. 
MK. SHIFT Set if SHIFT key is down. 


lParam Contains the x and y coordinates of the mouse cur- 
sor. The 2-coordinate is in the low-order word; the 
y-coordinate is in the high-order word. These coor- 
dinates are always relative to the upper-left corner 
of the window. 


WM_LBUTTONUP 


This message occurs when the user releases the left mouse button. 


Parameter Description 

wParam Contains a value that indicates whether various virtual 
keys are down. It can be any combination of the follow- 
ing values: 
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lParam 


WM_ MBUTTONDBLCLK 


Value Meaning 


MK. CONTROL — Set if CONTROL key is down. 
MIX MBUTTON _— Set if middle button is down. 
MK_ RBUTTON © Set if right button is down. 
Mk~ SHIFT Set if SHIFT key is down. 


Contains the # and ycoordinates of the mouse cur- 
sor. The 2-coordinate is in the low-order word; the 
y- coordinate is in the high-order word. These coor- 
dinates are always relative to the upper-left corner 
of the window. 


WM_- MBUTTONDBLCLKI 


This message occurs when the user double-clicks the middle mouse button. 


Parameter 


wParam 


lParam 


Comments 


Description 


Contains a value that indicates whether various virtual 
keys are down. It can be any combination of the follow- 
ing values: 


Value Meaning 


MK CONTROL — Set if CONTROL key is down. 
MK. LBUTTON © Set if left button is down. 
MK MBUTTON _ Set if middle button is down. 
MK RBUTTON — Set if right button is down. 
MK SHIFT Set if SHIFT key is down. 


Contains the a- and ycoordinates of the mouse cur- 
sor. The z-coordinate is in the low-order word; the 
y-coordinate is in the high-order word. These coor- 
dinates are always relative to the upper-left corner 
of the window. 


Only windows whose window class has CS.. DBLCLKS style can receive 
double-click messages. Windows generates a double-click message when 
the user presses, releases, and then presses a mouse button again within 
the system’s double-click time limit, Double-clicking actually generates 


671 


WM_MBUTTONDBLCLK 


four messages: a down-click message, an up-click message, the double- 
click message, and another up-click message. 


WM_MBUTTONDOWN 


This message occurs when the user presses the middle mouse button. 


Parameter Description 

wParam Contains a value that indicates whether various virtual 
keys are down. It can be any combination of the follow- 
ing values: 

Value Meaning 

MK... CONTROL — Set if CONTROL key is down. 
MK_LBUTTON _ Set if left button is down. 
MK_RBUTTON © Set if right button is down. 
MK SHIFT Set if SHIFT key is down. 

[Param Contains the x and ycoordinates of the mouse cur- 
sor. The #-coordinate is in the low-order word; the 
y-coordinate is in the high-order word. These coor- 
dinates are always relative to the upper-left corner 
of the window. 

WM_MBUTTONUP 


This message occurs when the user releases the middle mouse button. 


Parameter 


wParam 
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Description 


Contains a value that indicates whether various virtual 
keys are down. It can be any combination of the follow- 
ing values: 


Value Meaning 


MK~ CONTROL _ Set if CONTROL key is down. 
MK_LBUTTON _ Set if left button is down. 
MK RBUTTON _ Set if right button is down. 
MK~ SHIFT Set if SHIFT key is down. 


aac 


[Param 


WM_ MENUCHAR 


Contains the # and ycoordinates of the mouse cur- 
sor. The 2-coordinate is in the low-order word; the 
y-coordinate is in the high-order word. These coor- 
dinates are always relative to the upper-left corner 
of the window. 


WM_MENUCHAR 


This message is sent when the user presses a menu accelerator character 
that doesn’t match any of the predefined accelerators in the current menu. 
It is sent to the window that owns the menu. 


Parameter 


wParam 


lParam 


Return Value 


Description 


Contains the ASCII character that the user pressed. 


The high-order word contains a handle to the selected 
menu. The low-order word contains the MF..PPOPUP 
flag if the menu is a pop-up menu. It contains the 
MF_SYSMENU flag if the menu is a system menu. 


The high-order word of the return value contains one of the following com- 


mand codes: 
Code 


0 


Meaning 


Informs the menu manager that it should discard the char- 
acter that the user pressed, and creates a short beep on the 
system speaker. 


Informs the menu manager that it should close the current 
menu. | 


Informs the menu manager that the low-order word of the 
return value contains the menu item-number for a specific 
item. This item is selected by the menu manager. 


The low-order word is ignored if the high-order word contains zero or 1. 
Applications should process this message when accelerators are used to 
select bitmaps placed in a menu. 
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WML MEINUSELECT 


WM_MENUSELECT 


This message occurs when the user selects a menu item. 


Parameter Description 
wParam Contains a menu-command value. 
lParam The low-order word contains a combination of the fol- 
lowing menu flags: 
Value Meaning 
MF_ BITMAP Item is a bitmap. 
MF_ CHECKED Item is checked. 
MF_ DISABLED Item is disabled. 
MF_ GRAYED Item is grayed. 
MF_ HELP Item is the help item. 
MF... MOUSESELECT _ Item was selected with a 
mouse. 
MF. POPUP Item is contained in a pop-up 
menu. 
MF_SYSMENU Item is contained in the system 
menu. 
The high-order word identifies the menu associated with 
the message. 
WM_ MOUSEACTIVATE 


This message occurs when the cursor is in an inactive window and a mouse 
button is pressed. This message is sent to both parent and child windows. 


Parameter 


wParam 


lParam 
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Description 


Contains a handle to the topmost parent window of the 
window being activated. 


Contains the hit-test area code in the low-order word 
and the mouse message number in the high-order word. 
A hit test is a test that determines the location of the 
mouse pointer. 


Comments 


WM_ MOUSEMOVE 


The DefWindowProc function passes this message to a window’s parent 
window before any processing occurs. If the parent window returns TRUE, 


processing is halted. 


For a description of the individual hit-test area codes, see Table 5.2. 


WM_~ MOUSEMOVE 


This message occurs when the user moves the mouse. 


Parameter Description 

wParam Contains a value that indicates whether various virtual 
keys are down. It can be any combination of the follow- 
ing values: 
Value Meaning 
MK~ CONTROL — Set if CONTROL key is down. 
MK_LBUTTON _ Set if left button is down. 
MK_MBUTTON _ Set if middle button is down. 
MK_RBUTTON © Set if right button is down. 
MK SHIFT Set if SHIFT key is down. 

[Param Contains the 2- and ycoordinates of the mouse cur- 


sor. The z coordinate is in the low-order word; the 
y-coordinate is in the high-order word. These coor- 
dinates are always relative to the upper-left corner 


of the window. 


Comments 


The MAKEPOINT macro can be used to convert the [Param parameter 


toa POINT structure. 
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WM_ MOVE 


WM_ MOVE 


This message is sent when a window is moved. 


Parameter Description 
wParam Is not used. 
[Param Contains the new location of the upper-left corner of the 


client area of the window. This new location is given in 
screen coordinates for overlapped and pop-up windows 
and parent-client coordinates for child windows. The 
a-coordinate is in the low-order word; the ycoordinate 
is in the high-order word. 


WM_NCACTIVATE 


This message is sent to a window when its non-client area needs to be 
changed to indicate an active or inactive state. 


Parameter Description 
wParam Specifies when a caption bar or icon needs to be changed 
to indicate an active or inactive state. The wParam 


parameter is nonzero if an active caption or icon 1s to be 
drawn. It is zero for an inactive caption or icon. 


lParam Is not used. 


Default Action 


The DefWindowProc function draws a gray caption bar for an inactive 
window and a black caption bar for an active window. 


WM_NCCALCSIZE 


This message is sent when the size of a window’s client area needs to be 
calculated. 


Parameter Description 
wParam Is not used. 
lParam Points to a RECT data structure that contains the 


screen coordinates of the window rectangle neues 
client area, borders, caption, scroll bars, and so on). 
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WM_ NCDESTROY 


Default Action 
The DefWindowProc function calculates the size of the client area, 


based on the window characteristics (presence of scroll bars, menu, and 
so on), and places the result in the RECT data structure. 


WM_ NCCREATE 


This message is sent prior to the WM_ CREATE message when a window 
is first created. 


Parameter Description 
wParam Contains a handle to the window that is being created. 
lParam Points to the CREATESTRUCT data structure for 


the window. 


Return Value 


The return value is nonzero if the non-client area is created. It is zero if an 
error occurs; the Create Window function will return NULL in this case. 


Default Action 


Scroll bars are initialized (the scroll-bar position and range are set) and 
the window text is set. Memory used internally to create and maintain the 
window is allocated. 


WM_NCDESTROY 


This message informs a window that its non-client area is being destroyed. 
The Destroy Window function sends the WM. NCDESTROY message to 
the window following the WM_ DESTROY message. This message is used 
to free the allocated memory block associated with the window. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
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WM. NCDESTROY 


Default Action 


This message frees any memory internally allocated for the window. 


WM_NCHITTEST 


This message is sent to the window that contains the mouse cursor (or the 
window that used the GetCapture function to capture the mouse input) 
every time the mouse is moved. 


Parameter 


wParam 


lParam 


Return Value 


Description 


Is not used. 


Contains the « and ycoordinates of the mouse cur- 
sor. The 2-coordinate is in the low-order word; the 
y-coordinate is in the high-order word. These coor- 
dinates are always screen coordinates. 


The return value of the DefWindowProc function is one of the values given 
in Table 5.2, indicating the position of the mouse cursor: 


Table 5.2 
Hit-Test Codes 


Code 


HTBOTTOM 
HTBOTTOMLEFT 


Meaning 


In the lower horizontal border of window. 
In the lower-left corner of window border. 


HTBOTTOMRIGHT In the lower-right corner of window border. 


HTCAPTION 
HTCLIENT 
HTERROR 


HTGROWBOX 
HTLEFT 
HTMENU 
HTNOWHERE 


HTREDUCE 
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In a caption area. 
In a client area. 


Same as HTNOWHERE except that the 
DefWindowProc function produces a 
system beep to indicate an error. 


In a size box. 
In the left border of window. 
In a menu area. 


On the screen background or on a dividing line 
between windows. 


In a minimize box. 


WM_ NCLBUTTONDBLCLK. 


Table 5.2 (continued) 


Code 


HTRIGHT 
HTHSCROLL 


HTVSCROLL 
HTSIZE 


HTSYSMENU 


HTTOP 
HTTOPLEFT 
HTTOPRIGHT 
HTTRANSPARENT 


HTZOOM 


Comments 


Meaning 


In the right border of window. 
In the horizontal scroll bar. 
In the vertical scroll bar. 


Same as HTGROWBOX. 


In a control-menu box (close box in child 
windows). 


In the upper horizontal border of window. 
In the upper-left corner of window border. 
In the upper-right corner of window border. 


In a window currently covered by another 
window. 


In a maximize box. 


The MAKEPOINT macro can be used to convert the [Param parameter 
toa POINT structure. 


WM_ NCLBUTTONDBLCLK 


This message is sent to a window when the user double-clicks the left 
mouse button while the mouse cursor is in a non-client area of the window. 


Parameter Description 


wParam Contains the code returned by WM_ NCHITTEST 
(for more information, see the WM_ NCHITTEST 


message, earlier in this chapter). 


lParam Points to a POINT data structure that contains the 
z- and yscreen coordinates of the mouse position. 
These coordinates are always relative to the upper- 
left corner of the screen. 


Default Action 


If appropriate, WM_SYSCOMMAND messages are sent. 
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WM_ NCLBUTTONDOWN 


WM_ NCLBUTTONDOWN 


This message is sent to a window when the user presses the left mouse but- 
ton while the mouse cursor is in a non-client area of the window. 


Parameter Description 


wParam Contains the code returned by WM— NCHITTEST 
(for more information, see the WM_ NCHITTEST 


message, earlier in this chapter). 


lParam Points to a POINT data structure that contains the 
a and yscreen coordinates of the mouse position. 
These coordinates are always relative to the upper- 
left corner of the screen. 


Default Action 


If appropriate, WM SYSCOMMAND messages are sent. 


WM_ NCLBUTTONUP 


This message is sent to a window when the user releases the left mouse 
button while the mouse cursor is in a non-client area of the window. 


Parameter Description 


wParam Contains the code returned by WM_ NCHITTEST 
(for more information, see the WM_ NCHITTEST 


message, earlier in this chapter). 


lParam Points to a POINT data structure that contains the 
a- and y-screen coordinates of the mouse position. 
These coordinates are always relative to the upper- 
left. corner of the screen. 


Default Action 
If appropriate, WM SYSCOMMAND messages are sent. 
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WM_ NCMBUTTONDOWN 


WM_ NCMBUTTONDBLCLK 


This message 1s sent to a window when the user double-clicks the middle 
mouse button while the mouse cursor is in a non-client area of the window. 


Parameter 


wParam 


lParam 


Description 


Contains the code returned by WM_ NCHITTEST 
(for more information, see the WM_ NCHITTEST 
message, earlier in this chapter). 


Points to a POINT data structure that contains the 
a and yscreen coordinates of the mouse position. 
These coordinates are always relative to the upper- 
left corner of the screen. | 


WM.~ NCMBUTTONDOWN 


This message is sent to a window when the user presses the middle mouse 
button while the mouse cursor is in a non-client area of the window. 


Parameter 


wParam 


lParam 


Description 


Contains the code returned by WM_ NCHITTEST 
(for more information, see the WM_ NCHITTEST 


message, earlier in this chapter). 


Points to a POINT data structure that contains the 
z and yscreen coordinates of the mouse position. 
These coordinates are always relative to the upper- 
left corner of the screen. 
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WM_ NCMBUTTONUP 


WM_NCMBUTTONUP 


This message is sent to a window when the user releases the left mouse 
button while the mouse cursor is in a non-client area of the window. 


Parameter Description 


wParam Contains the code returned by WM_ NCHITTEST 
(for more information, see the WM_ NCHITTEST 
message, earlier in this chapter). 


lParam Points to a POINT data structure that contains the 
a- and yscreen coordinates of the mouse position. 
These coordinates are always relative to the upper- 
left corner of the screen. 


WM_ NCMOUSEMOVE 


This message is sent to a window when the mouse cursor is moved in a 
non-client area of the window. 


Parameter Description 


wParam Contains the code returned by WM NCHITTEST 
(for more information, see the WM_ NCHITTEST 


message, earlier in this chapter). 


[Param Points to a POINT data structure that contains the 
a and ¥screen coordinates of the mouse position. 
These coordinates are always relative to the upper- 
left corner of the screen. 

Default Action 


If appropriate, WM_SYSCOMMAND messages are sent. 


WM_NCPAINT 


This message is sent to a window when its frame needs painting. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 
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WM_ NCRBUTTONDOWN 


Default Action 


The DefWindowProc function paints the window frame. 


Comments 


An application can intercept this message and paint its own custom win- 
dow frame. Remember that the clipping region for a window is always 
rectangular, even if the shape of the frame is altered. 


WM. NCRBUTTONDBLCLK 


This message is sent to a window when the user double-clicks the right 
mouse button while the mouse cursor is In a non-client area of the window. 


Parameter Description 


wParam Contains the code returned by WM.. NCHITTEST 
(for more information, see the WM_ NCHITTEST 


message, earlier in this chapter). 


[Param Points to a POINT data structure that contains the 
a and yscreen coordinates of the mouse position. 
These coordinates are always relative to the upper- 
left corner of the screen. 


WM_NCRBUTTONDOWN 


This message is sent to a window when the user presses the right mouse 
button while the mouse cursor is in a non-client area of the window. 


Parameter Description 


wParam Contains the code returned by WM_ NCHITTEST 
_ (for more information, see the WM_ NCHITTEST 
message, earlier in this chapter). 


lParam Points to a POINT data structure that contains the 
a and yscreen coordinates of the mouse position. 
These coordinates are always relative to the upper- 
left corner of the screen. 
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WM_ NCRBUTTONUP 


WM_ NCRBUTTONUP 


This message is sent to a window when the user releases the right mouse 
button while the mouse cursor is in a non-client area of the window. 


Parameter 


wParam 


[Param 


Description 


Contains the code returned by WM_ NCHITTEST 
(for more information, see the WM_ NCHITTEST 
message, earlier in this chapter). 


Points to a POINT data structure that contains the 
a and screen coordinates of the mouse position. 
These coordinates are always relative to the upper- 
left corner of the screen. 


WM_ NEXTDLGCTL 


This message is sent to a dialog box’s window function, to alter the 
control focus. The effect of this message is different than that of the 
SetFocus function because WM_ NEXTDLGCTL modifies the 
border around the default button. 


Parameter 


wParam 


lParam 


Comments 


Description 


If the [Param parameter is nonzero, the wParam param- 
eter identifies the control that receives the focus. If 
lParam is zero, wParam is a flag that indicates whether 
the next or previous control with tab-stop style receives 
the focus. If wParam is zero, the next control receives 
the focus; otherwise, the previous control with tab-stop 
style receives the focus. 


Contains a flag that indicates how Windows uses the 
wParam parameter. If the [Param parameter is nonzero, 
wParam is a handle associated with the control that 
receives the focus; otherwise, wParam is a flag that indi- 
cates whether the next or previous control with tab-stop 
style receives the focus. 


Do not use the SendMessage function to send a WM_ NEXTDLGCTL 
message if your application will concurrently process other messages that 
set the control focus. Use the PostMessage function instead. 
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WML_ PAINTCLIPBOARD 


WM_PAINT 


This message is sent when Windows or an application makes a request to 
repaint a portion of an application’s window. The message is sent either 
when the Update Window function is called or by the DispatchMessage 
function when the application obtains a WM_ PAINT message by using 
the GetMessage or PeekMessage function. 


Parameter Description 
wParam {s not used. 
lParam Is not used. 
WM_PAINTCLIPBOARD 


This message is sent when the clipboard contains a data handle for the 
CF..OWNERDISPLAY format (that is, the clipboard owner should display 
the clipboard contents) and the clipboard application’s client area needs 
repainting. The WM_PAINTCLIPBOARD message is sent to the clip- 
board owner to request repainting of all or part of the clipboard appli- 
cation’s client area. 


Parameter Description 
wParam Contains a handle to the clipboard-application window. 
[Param The low-order word of the [Param parameter identifies a 


PAINTSTRUCT data structure that defines what 
part of si client area to paint. The high-order word is 
not used. 


Comments 


To determine whether the entire client area or just a portion of it needs 
repainting, the clipboard owner must compare the dimensions of the draw- 
ing area given in the repaint field of the PAINTSTRUCT data struc- 
ture to the dimensions given in the most recent WM_ SIZECLIPBOARD 


message. 


An application must use the GlobalLock function to lock the memory 
that contains the PAINTSTRUCT data structure. The application 
should unlock that memory by using the GlobalUnlock function before 
it yields or returns control. 
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WWM_ PASTE 


WM_PASTE 


This message inserts the data from the clipboard into the control window 
at the current cursor position. Data are inserted only if the clipboard con- 


tains data in CF_ TEXT format. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
WM_ QUERYENDSESSION 


This message is sent when the user chooses the End Session command. If 
any application returns zero, the session is not ended. Windows stops 
sending WM. QUERYENDSESSION messages as soon as one application 
returns zero, and sends WM_ ENDSESSION messages, with the wParam 
parameter set to zero, to any applications that have already returned 
nonzero. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


Return Value 


The return value is nonzero if the application can be conveniently shut 
down. Otherwise, it is zero. 


Default Action 


The DefWindowProc function returns nonzero. 
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WM_ RBUTTONDBLCLK 


WM... QUERYOPEN 


This message is sent to an icon when the user requests that it be opened 
into a window. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


Return Value 


The return value is zero when the application prevents the icon from being 
opened. It is nonzero when the icon can be opened. 


Default Action 


The DefWindowProc function returns nonzero. 


WM_ QUIT 


This message indicates a request to terminate an application and is gen- 
erated when the application calls the PostQuitMessage function. It 
causes the GetMessage function to return zero. 


Parameter Description 

wParam Contains the exit code given in the PostQuitMessage 
call. 

lParam Is not used. 

WM_ RBUTTONDBLCLK 


This message occurs when the user double-clicks the right mouse button. 


Parameter Description 

wParam Contains a value that indicates whether various virtual 
keys are down. It can be any combination of the follow- 
ing values: 
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WM_RBUTTONDBLCLK 


lParam 


Comments 


Value Meaning 


MK CONTROL _ Set if CONTROL key is down. 
MK_LBUTTON _ Set if left button 1s down. 
MK_MBUTTON | Set if middle button is down. 
MK_RBUTTON _ Set if right button is down. 
MK SHIFT Set if SHIFT key is down. 


Contains the x and ycoordinates of the mouse cur- 
sor. The #coordinate is in the low-order word; the 
y-coordinate is in the high-order word. These coor- 
dinates are always relative to the upper-left corner 
of the window. 


Only windows whose window class has CS_ DBLCLKS style can receive 
double-click messages. Windows generates a double-click message when 
the user presses, releases, and then presses a mouse button again within 
the system’s double-click time limit. Double-clicking actually generates 
four messages: a down-click message, an up-click message, the double- 
click message, and another up-click message. 


WM_RBUTTONDOWN 


This message occurs when the user presses the right mouse button. 


Parameter 


wParam 
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Description 


Contains a value that indicates whether various virtual 
keys are down. It can be any combination of the follow- 
ing values: 


Value Meaning 


MK CONTROL _ Set if CONTROL key is down. 
MK LBUTTON _ Set if left button is down. 
MK MBUTTON _ Set if middle button is down. 
MK_ SHIFT Set if SHIFT key is down. 


WML RENDERALLFORMATS 


lParam Contains the z and ycoordinates of the mouse cur- 
sor. The zcoordinate is in the low-order word; the 
ycoordinate is in the high-order word. These coor- 
dinates are always relative to the upper-left corner 
of the window. 


WM. RBUTTONUP 


This message occurs when the user releases the right mouse button. 


Parameter Description 

wParam Contains a value that indicates whether various virtual 
keys are down. It can be any combination of the follow- 
ing values: 
Value Meaning 


MK~ CONTROL — Set if CONTROL key is down. 
MK. LBUTTON _— Set if left button is down. 
MK. MBUTTON _ Set if middle button is down. 
MK SHIFT Set if SHIFT key is down. 


[Param Contains the a and y coordinates of the mouse cur- 
sor. The xcoordinate is in the low-order word; the 
y-coordinate is in the high-order word. These coor- 
dinates are always relative to the upper-left corner 
of the window. 


WM_ RENDERALLFORMATS 


This message is sent to the application that owns the clipboard when that 
application is being destroyed. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
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WM_ RENDERALLFORMATS 


Comments 


The application should render the clipboard data in all the formats 

it is capable of generating and pass a handle to each format to the 
SetClipboardData function. This ensures that the data in the clip- 
board can be rendered even though the application has been destroyed. 


WM. RENDERFORMAT 


This message requests that the clipboard owner format the data last 
copied to the clipboard in the specified format, and then pass a handle 
to the formatted data to the clipboard. 


Parameter Description 

wParam Specifies the data format. It can be any one of the for- 
mats described with the SetClipboardData function. 

lParam Is not used. 

WM_SETCURSOR 


This message occurs if mouse input is not captured and the system mouse 
causes cursor movement within a window. 


Parameter Description 


wParam Contains a handle to the window that contains the 
mouse pointer. 


lParam Contains the hit-test area code in the low-order word 
and the mouse message number in the high-order word. 


Comments 


The DefWindowProc function passes the WM_SETCURSOR message 
to a parent window before processing. If the parent window returns 
TRUE, further processing is halted. Passing the message to a window’s 
parent window gives the parent window control over the cursor’s setting 
in a child window. The DefWindowProc function also uses this mes- 
sage to set the cursor to an arrow if it is not in the client area, or to the 
registered-class cursor if it is. If the low-order word of the /Param parame- 
ter is HTERROR and the high-order word of [Param is a mouse button- 
down message, the MessageBeep function is called. 
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WM_SETREDRAW 


WM_SETFOCUS 


This message is sent after a window gains the input focus. 


Parameter Description | 

wParam Contains the handle of the window that loses the input 
focus (may be NULL). 

[Param Is not used. 

Comments 


To display a caret, an application should call the appropriate caret func- 
tions at this point. 


WM_SETREDRAW 


This message is sent by an application to a window in order to allow 
changes in that window to be redrawn, or to prevent changes in that 
window from being redrawn. 


Parameter Description 


wParam Specifies the state of the redraw flag. If the wParam 
parameter is nonzero, the redraw flag is set. If wParam 
is zero, the flag is cleared. 


lParam Is not used. 


Comments 


This message sets or clears the redraw flag. However, it does not direct a 
list box to update its display. When the redraw flag is set, a control can be 
redrawn immediately after each change. When the redraw flag is cleared, 
no redrawing is done. Applications that need to add several names to a list 
without redrawing until the final name is added should set the redraw flag 
before adding the final name to the list. 
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WM_SETTEXT 


WM_SETTEXT 


This message is used to set the text of a window. For edit controls, the 
text to be set is the content of the control. For button controls, the text 
is the button name. For other windows, the text is the window caption. 


Parameter Description 

wParam Is not used. 

lParam Points to a null-terminated string that is the window 
text. 

WM_SETVISIBLE 


This message is sent immediately before a window is made visible or 
hidden. 


Parameter Description 


wParam Specifies whether the window is being made visible or 
invisible. It is nonzero if the window is being made visi- 
ble. It is zero if it is being made invisible. 


lParam Is not used. 


WM_SHOWWINDOW 


This message is sent when a window is to be hidden or shown. A window 
is hidden or shown when the Show Window function is called, an over- 
lapped window is maximized or restored, or an overlapped or pop-up win- 
dow is closed (made iconic) or opened (displayed on the screen). When an 
overlapped window is closed, all pop-up windows associated with that win- 
dow are hidden. 


Parameter Description 

wParam Specifies whether a window is being shown. It is nonzero 
if the window is being shown. It is zero if the window 1s 
being hidden. 

lParam Specifies the status of the window being shown. It is zero 


if the message is sent because of a Show Window func- 
tion call. Otherwise, the [Param parameter is one of the 
following values: 
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WM_ SIZE 


Value Meaning 
SW_. OTHERUNZOOM 


Another window is being made 
iconic. 
SW. OTHERZOOM Another window is being maxi- 


mized. | 


SW_ PARENTCLOSING 
Parent window is closing 
(being made iconic) or a 
pop-up window is being 


hidden. 
SW_PARENTOPENING 


Parent window is opening 
(being displayed) or a pop- 
up window is being shown. 


Default Action 


The DefWindowProc function hides or shows the window as specified by 
the message. 


WWML_ SIZE 
This message is sent after the size of a window has changed. 
Parameter Description 


wParam Contains a value that defines the type of resizing 
requested. It can be one of the following values: 


Value Meaning 

SIZEFULLSCREEN Window has been made full- 
screen. 

SIZEICONIC Window has been made iconic. 

SIZENORMAL Window has been resized, but 
neither SIZEICONIC nor 


SIZEFULLSCREEN applies. 
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WM_SIZE 


SIZEZOOMHIDE Message is sent to all pop-up 
windows when some other win- 
dow is zooming to full-screen. 


SIZEZOOMSHOW Message is sent to all pop-up 
windows when some other win- 
dow has been restored to its 
former size. 


[Param Contains the new width and height of the client area 
of the window. The width is in the low-order word; the 
height is in the high-order word. 


Comments 


If the SetScrollPos or MoveWindow function is called for a child win- 
dow as a result of the WM_SIZE message, the bRedraw parameter should 
be nonzero to cause the window to be repainted. 


WM_ SIZECLIPBOARD 


This message is sent when the clipboard contains a data handle for the 
CF. OWNERDISPLAY format (that is, the clipboard owner should display 
the clipboard contents) and the clipboard-application window has changed 
size. 


Parameter Description 
wParam Identifies the clipboard-application window. 
lParam The low-order word of the [Param parameter identifies a 


RECT data structure that specifies the area the clip- 
board owner should paint. The high-order word is not 
used. 


Comments 


A WM_SIZECLIPBOARD message is sent with a null rectangle (0,0,0,0) 
as the new size when the clipboard application is about to be destroyed or 
made iconic. This permits the clipboard owner to free its display resources. 


An application must use the GlobalLock function to lock the memory 
that contains the PAINTSTRUCT data structure. The application 
should unlock that memory by using the GlobalUnlock function before 
it yields or returns control. 
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WM_SYSCHAR 


WM_SYSCHAR 


This message results when a WM_SYSKEYUP and WM_SYSKEYDOWN 
message are translated. It specifies the virtual keycode of the system- 
menu key. 


Parameter Description 
wParam Contains the virtual keycode of a system-menu key. 
lParam Contains the repeat count, scan code, key-transition 


code, previous key state, and context code, as shown in 
the following list. In this list, bit 1 is the low-order bit: 


Bit Value 
0-15 Repeat count (the number of times the key- 


stroke is repeated as a result of the user 
holding down the key). 


16-23 Scan code (OEM-dependent value). 
24-28 Not used. 
29 Context code (1 if the ALT key is held down 
while the key is pressed, 0 otherwise). 
30 Previous key state (1 if the key is down 
before the message is sent, 0 if the key 
is up). 
31 Transition state {1 if the key is being 
released, 0 if the key is being pressed). 
Default Action 
None 
Comments 


When the context code is zero, the message can be passed to the 
TranslateAccelerator function, which will handle it as though it 
were a normal key message instead of a system-key message. This 
allows accelerator keys to be used with the active window even if 
the active window does not have the focus. 
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WM_ SYSCOLORCHANGE, 


WM_ SYSCOLORCHANGE 


This message specifies a change in one or more system colors. Windows 
sends the message to all top-level windows when a change is made in the 
system color setting. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
Default Action 


Windows sends a WM_PAINT message to any window that is affected by 
a system color change. 


Comments 


Applications that have brushes that use the system colors should delete 
those brushes and re-create them by using the new system colors. 


WM_SYSCOMMAND 


This message is sent when the user selects a command from the system 
menu or when the user selects the maximize or minimize box. 


Parameter Description 
wParam Specifies the type of system command requested. It can 
be any one of the following values: 
Value Meaning 
SC.. CLOSE Close the window. 
SC_ HSCROLL Scroll horizontally. 
SC_ KEYMENU Retrieve a menu through a 
keystroke. 
SC.. MAXIMIZE Zoom the window. 
(or SC_ ZOOM) 
SC__MINIMIZE Make the window iconic. 7 


(or SC_ICON) 
SC_ MOUSEMENU Retrieve a menu through a 


mouse click. 
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WM_SYSCOMMAND 


SC_ MOVE Move the window. 
SC. NEXTWINDOW Move to the next window. 
SC..PREVWINDOW — Move to the previous window. 


SC_.. RESTORE Checkpoint (save the previous 
coordinates). 
SC_ SIZE Size the window. 
SC_ VSCROLL Scroll vertically. 
lParam Contains the mouse-cursor coordinates if a system-menu 


command is chosen with the mouse. The low-order word 
contains the zcoordinate, and the high-order word con- 
tains the ycoordinate. Otherwise, this parameter is not 
used. 


Default Action 


The DefWindowProc function carries out the system-menu request for 
the predefined actions specified above. 


Comments 


In WM_ SYSCOMMAND messages, the four low-order bits of the wParam 
parameter are used internally by Windows. When an application tests the 
value of wParam, it must combine the value FFFO (hexadecimal) with the 
rife value by using the bitwise AND operator to obtain the correct 
result. 


The menu items in a system menu can be modified by using the 
GetSystemMenu and ChangeMenu functions. Applications that 
modify the system menu must process WMW—~SYSCOMMAND messages. 
Any WM_~SYSCOMMAND messages not handled by the application 
must be passed to the DefWindowProc function. Any command values 
added by an application must be processed by the application and cannot 
be passed to DefWindowProc. 


An application can carry out any system command at any time by passing 


a WM_ SYSCOMMAND message to the DefWindowProc function. 
Accelerator keystrokes that are defined to select items from the system 


menu are translated into WM_SYSCOMMAND messages; all other 
accelerator keystrokes are translated into WM—_ COMMAND messages. 
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WM_ SYSDEADCHAR 
This message results when a WMW_SYSKEYUP and WM_SYSKEYDOWN 


message are translated. It specifies the character value of a dead key. 


Parameter Description 
wParam Contains the dead-key character value. 
lParam Contains a repeat count and an auto-repeat count. The 


low-order word contains the repeat count; the high- 
order word contains the auto-repeat count. 


WM_SYSKEYDOWN 


This message is sent when the user holds down the ALT key and then 
presses another key. It also occurs when no window currently has the input 
focus; in this case, the WM_SYSKEYDOWN message is sent to the active 
window. The window that receives the message can distinguish between 
these two contexts by checking the context code in the (Param parameter. 


Parameter Description 
wParam Contains the virtual keycode of the key being pressed. 
lParam Contains the repeat count, scan code, key-transition 


code, previous key state, and context code, as shown in 
the following list. In this list, bit 1 is the low-order bit: 


Bit Value 


0-15 Repeat count (the number of times the key- 
stroke is repeated as a result of the user 
holding down the key). 


16-23 Scan code (OEM-dependent value). 
24-28 Not used. 
29 Context code (1 if the ALT key is held down 


while the key is pressed, 0 otherwise). 
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30 Previous key state (1 if the key is down 
before the message is sent, 0 if the key 
is up). 

31 Transition state (1 if the key is being 


released, 0 if the key is being pressed). 


For WM_SYSKEYDOWN messages, the key-transition bit 
(bit 31) is 0. The context-code bit (bit 29) is 1 if the ALT key 
is down while the key is pressed; it is 0 if the message is 
one to the active window because no window has the input 
ocus. 


Comments 


When the context code is zero, the message can be passed to the 
TranslateAccelerator function, which will handle it as though it 
were a normal key message instead of a system-key message. This 
allows accelerator keys to be used with the active window even if the 
active window does not have the focus. 


Because of auto-repeat, more than one WM_SYSKEYDOWN message may 
occur before a WM_SYSKEYUP message is sent. The previous key state 
(bit 30) can be used to determine whether the WM_SYSKEYDOWN mes- 


sage indicates the first down transition or a repeated down transition. 


WM_SYSKEYUP 


This message is sent when the user releases a key that was pressed while 
the ALT key was held down. It also occurs when no window currently has 
the input focus; in this case, the WM_SYSKEYUP message is sent to the 
active window. The window that receives the message can distinguish 
between these two contexts by checking the context code in the (Param 
parameter. 


Parameter Description 
wParam Contains the virtual keycode of the key being released. 
lParam Contains the repeat count, scan code, key-transition 


code, previous key state, and context code, as shown in 
the following list. In this list, bit 1 is the low-order bit: 
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Bit Value 


0-15 Repeat count (the number of times the key- 
stroke is repeated as a result of the user 
holding down the key). 


16-23 Scan code (OEM-dependent value). 

24-28 Not used. 

29 Context code (1 if the ALT key is held down 
while the key is pressed, 0 otherwise). 

30 Previous key state (1 if the key is down 
before the message is sent, 0 if the key 
is up). | 

31 Transition state 5 if the key is being 
released, 0 if the key is being pressed). 


For WM_SYSKEYUP messages, the key-transition bit 
(bit 31) is 1. The context-code bit (bit 29) is 1 if the ALT 
key is down while the key is pressed; it is 0 if the message 
is sent to the active window because no window has 

the input focus. 


Comments 


When the context code is zero, the message can be passed to the 
TranslateAccelerator function, which will handle it as though it were 
a normal key message instead of a system-key message. This allows accel- 
erator keys to be used with the active window even if the active window 
does not have the focus. 


WM_SYSTEMERROR 


This message is sent to all top-level windows when an out-of-memory 
system error occurs. 


Parameter Description 

wParam Contains the value 8, indicating a DOS out-of-memory 
error. 

lParam Is not used. 
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Default Action 


The MS-DOS Executive window alerts the user to the out-of-memory 
condition. 


Comments 


Applications do not need to process this message since the out-of-memory 
condition is handled by the MS-DOS Executive. 


WM. TIMECHANGE 


This message occurs when an application makes a change (or set of 
changes) to the system time. Any application that changes the system 
time should send this message to all top-level windows. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
Comments 


To send the WM_ TIMECHANGE message to all top-level windows, an 
application can use the SendMessage function with the hWnd parameter 
set to FFFF (hexadecimal). 


WM_ TIMER 


This message occurs when the time limit set for a given timer has elapsed. 


Parameter Description 

wParam Contains the timer ID, an integer value that identifies 
the timer. 

lParam Points to a function that was passed to the Set Timer 


function when the timer was created. If the lParam 
parameter is not NULL, it calls the specified function 
directly, instead of sending the WM_ TIMER message 


to the window function. 
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WM_ VSCROLL 


This message is sent when the user clicks the vertical scroll bar. 


Parameter 


wParam 


lParam 


Comments 


Description 


Contains a scroll-bar code that specifies the user’s scroll- 
ing request. It can be any one of the following values: 


Value 


SB_. BOTTOM 

SB_ ENDSCROLL 

SB_. LINEDOWN 

SB_ LINEUP 

SB_ PAGEDOWN 

SB_ PAGEUP 

SB_ THUMBPOSITION 
SB_ THUMBTRACK 


SB_ TOP 


Meaning 


Scroll to bottom. 

End scroll. 

Scroll one line down. 
Scroll one line up. 

Scroll one page down. 
Scroll one page up. 

Scroll to absolute position. 


Drag thumb to specified 
position. 


Scroll to top. 


If the message is sent by a scroll-bar control, the high- 
order word of the lParam parameter identifies the con- 
trol. If the message is sent as a result of the user clicking 
a pop-up window’s scroll bar, the high-order word 1s not 


used. 


The SB. THUMBTRACK message typically is used by applications that 
give some feedback while the thumb is being dragged. 


If an application scrolls the document in the window, it must also reset the 
position of the thumb by using the SetScrollPos function. 
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WM_ VSCROLLCLIPBOARD 


This message is sent when the clipboard contains a data handle for the 
CF_ OWNERDISPLAY format (that is, the clipboard owner should display 
the clipboard contents) and an event occurs in the clipboard-application’s 
vertical scroll bar. 


Parameter Description 
wParam Contains a handle to the clipboard-application window. 
[Param Contains one of the following scroll-bar codes in the 


low-order word: 


Value Meaning 

SB. BOTTOM Scroll to lower right. 

SB_ ENDSCROLL End scroll. 

SB_ LINEDOWN Scroll one line down. 

SB_ LINEUP Scroll one line up. 

SB_- PAGEDOWN Scroll one page down. 

SB. PAGEUP Scroll one page up. 

SB. THUMBPOSITION Scroll to absolute position. 
SB_ TOP Scroll to upper left. 


The high-order word of the [Param parameter con- 
tains the thumb position if the scroll-bar code is 
SB_ THUMBPOSITION. Otherwise, the high-order 


word is not used. 


Comments 


The clipboard owner should use the InvalidateRect function or repaint 
as desired. The scroll bar position should also be reset. 
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WM_ WININICHANGE 


This message is sent when the Windows initialization file, win.int, changes. 
Any application that makes a change to win.int should send this message 
to all top-level windows. 


Parameter Description 
wParam Is not used. 
lParam Points to a string that specifies the name of the section 


that has changed (the string does not include the square. 
brackets). If more than one section has changed, the 
[Param parameter is zero, and the application that 
receives the message must find and process the changes 
itself, 


Comments 


To send the WM_ WININICHANGE message to all top-level windows, an 
application can use the SendMessage function with the hWnd parameter 


set to FFFF (hexadecimal). 
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6.1 Introduction 


This chapter describes the data types and structures used by Microsoft 
Windows functions and messages. It contains two parts: a table of data 
types and a list of Windows data structures, each arranged alphabetically. 


6.2 Data Types 


The data types in the following list are keywords that define the size and 
meaning of parameters and return values associated with Windows func- 
tions. This list contains character, integer, and Boolean types, pointer 
types, and handles. The character, integer, and Boolean types are common 
to most C compilers. Most of the pointer-type names begin with either a 

P prefix (for short pointers) or an LP prefix (for long pointers). A short 
pointer accesses data within the current data segment; a long pointer con- 
tains a 32-bit segment /offset value. A Windows application uses a handle 
to refer to a resource that has been loaded into memory. Windows pro- 
vides access to these resources through internally maintained tables that 
contain individual entries for each handle. Each entry in the handle table 
contains the address of the resource and a means of identifying the 
resource type. The Windows data types are defined in the following list: 


Type Definition 

BOOL 16-bit Boolean value. 

BYTE Unsigned 8-bit integer. 

char ASCII character or a signed 8-bit integer. 

DWORD Unsigned 32-bit integer or a segment /offset address. 

FAR Data-type attribute that can be used to create a 
long pointer. 

FARPROC Long pointer to a function. 

GLOBALHANDLE 


Handle to global memory. It is a 16-bit index to a 
block of memory allocated from the system’s global 


heap. | 
HANDLE General handle. It represents a 16-bit index to a 
table entry that identifies program data. 
HBITMAP Handle to a physical bitmap. It is a 16-bit index to 


GDI’s physical drawing objects. 
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HBRUSH 
HCURSOR 
HDC 
HFONT 
HICON 
HMENU 
HPEN 
HRGN 
HSTR 

int 


LOCALHANDLE 


long 
LONG 
LPINT 
LPMSG 
LPRECT 
LPSTR 
NEAR 


PINT 
PSTR 
short 


void 


WORD 
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Handle to a physical brush. It is a 16-bit index to 
GDI’s physical drawing objects. 


Handle to a cursor resource. It is a 16-bit index to a 
resource-table entry. 


Handle to a display context. It is a 16-bit index to 
GDI’s device-context tables. 


Handle to a physical font. It is a 16-bit index to 
GDI’s physical drawing objects. 


Handle to an icon resource. It is a 16-bit index to a 
resource-table entry. 


Handle to a menu resource. It is a 16-bit index to a 
resource-table entry. 


Handle to a physical pen. It is a 16-bit index to 
GDI’s physical drawing objects. 


Handle to a physical region. It is a 16-bit index to 
GDI’s physical drawing objects. 


Handle to a string resource. It is a 16-bit index to a 
resource-table entry. 


Signed. 16-bit integer. 


Handle to local memory. It is a 16-bit index to a 
block of memory allocated from the application’s 
local heap. 


Signed 32-bit integer. 

Signed 32-bit integer. 

Long pointer to a signed 16-bit integer. 
Long pointer to an MSG data structure. 
Long pointer toa RECT data structure. 
Long pointer to a character string. 


Data-type attribute that can be used to create a 
short pointer. 


Pointer to a signed 16-bit integer. 
Pointer to a character string. 
Signed 16-bit integer. 


Empty value. It is used with a function to specify no 
return value. 


Unsigned 16-bit integer. 


BITMAP 


6.3 Data Structures 


This section lists data structures that are used by Windows. The data 
structures are presented in alphabetical order. The structure definition 
is given, followed by descriptions of its fields. 


BITMAP Bitmap Data Structure 


The BITMAP structure defines the height, width, color format, and bit 
values of a logical bitmap. 


typedef struct 
short 
short 
short 
short 
BYTE 
BYTE 
LPSTR 

} BITMAP; 


tagBITMAP { 
bmType; 
bmWidth: 
bmHeight; 
bmWidthBytes; 
bmPlanes; 
bmBitsPixel: 
bmBits; 


The BITMAP structure has the following fields: 


Field 


bmType 
bm Width 
bm Height 


bm WidthBytes 


bmPlanes 
bmBitsPixel 


bm Bits 


Description 


Specifies the bitmap type. For logical bitmaps, the 
bmType field must be zero. 


Specifies the width of the bitmap (in pixels). The 
width must be greater than zero. 


Specifies the height of the bitmap (in raster lines). 
The height must be greater than zero. 


Specifies the number of bytes in each raster line. 
This value must be an even number since GDI 
assumes that the bit values of a bitmap form an 
array of integer (two-byte) values. In other words, 
bm WidthBytes X 8 must be the next multiple of 
16 greater than or equal to the bm Width field. 


Points to the number of color planes in the bitmap. 


Points to the number of adjacent color bits on each 
plane needed to define a pixel. 


Points to the location of the bit values for the bit- 
map. The bmBits field must be a long pointer to an 
array of character (one-byte) values. 


609 


BITMAP 


Comments 


The currently used bitmap formats are monochrome and color. The mono- 
chrome bitmap uses a one-bit, one-plane format. Each scan is a multiple of 
16 bits. 


Scans are organized as follows for a monochrome bitmap of height n: 


Scan O 
Scan 1 


Scan n-2 
Scan n-1 


The pixels on a monochrome device are either black or white. If the 

corresponding bit in the bitmap is 1, the pixel is turned on (white); 

‘b the eee. bit in the bitmap is zero, the pixel is turned off 
lack). 


All devices that have the RC_BITBLT bit set in the device capabilities 
support bitmaps. 


The color bitmap uses a one-bit, three-plane format. This format applies 
to high-resolution and EGA high- and low-resolution drivers. Each scan is 
a multiple of 16 bits. 


Scans are organized as follows for a color bitmap of height n: 


Red Scan 0 

Red scan 1 

Red Sean 
~1 


n 
Red Scan n 
Green Scan O 
Green scan 1 


Green Scan 


n-2 
Green Scan n-l1 
Blue Scan O 
Blue Scan 1 
Blue scan n-2 
Blue Scan n-L 
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Pixels in a color plane correspond to bits in the bitmap, as follows: 


O = color disabled 
1 = color enabled 
See Also 


The CreateBitmapIndirect and GetObject functions in Chapter 3, 
“Functions Directory.” 


COMSTAT Communication-Device Status 


The COMSTAT structure contains information about a communications 
device. 


typedef struct tagCOMSTAT { 
BYTE fCtsHold: 1; 
BYTE fDsrHold: 1; 
BYTE fRlsdHold: 1; 
BYTE fXoffHold: 1; 
BYTE fXoffSent: 1; 
BYTE fEof: lL: 
BYTE fTxim: 1; 
WORD cbhInQue; 
WORD cbOutQue; 

} COMSTAT; 


The COMSTAT structure has the following fields: 


Field Description 

fCtsHold: 1 Specifies whether transmission is waiting for the 
clear-to-send (OTS) signal to be sent. 

fDsrHold: 1 Specifies whether transmission is waiting for the 
data-set-ready (DSR) signal to be sent. 

fRisdHold: 1 Specifies whether transmission is waiting for the 


-_receive-line-signal-detect (RLSD) signal to be sent. 


fXoffHold: 1 Specifies whether transmission is waiting as a result 
of the XoffChar character being received. 


fXoffSent: 1 Specifies whether transmission 1s walting as a result 
of the XoffChar character being transmitted. 
Transmission halts when the XoffChar character 
is transmitted and used by systems that take the 
next character as XON, regardless of the actual 
character. 
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fEof: 1 Specifies whether the EofChar character has been 
received. 

fTxim: 1 Specifies whether a character is waiting to be 
transmitted. 

cbInQue Specifies the number of characters in the receive 
queue. 

cbOutQue Specifies the number of characters in the transmit 
queue. 

See Also 


The GetCommError function in Chapter 3, “Functions Directory.” 


CREATESTRUCT Window-Creation Structure 


The CREATESTRUCT structure defines the initialization parameters 
passed to an application’s window function. 


typedef struct tagCREATESTRUCT { 


LPSTR lpCreateParams; 
HANDLE hInstance; 
HANDLE hMenu:; 
HWND hwndParent;: 
int cy; 

int cx; 

int y? 

Int. x: 

long style; 
LPSTR lpszName; 
LPSTR lpszClass; 


} CREATESTRUCT; 


The CREATESTRUCT structure has the following fields: 


cy 
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Field Description 

IpCreateParams _ Points to data to be used for creating the window. 

hInstance Identifies the module-instance handle of the module 
that owns the new window. 

hMenu Identifies the menu to be used by the new window. 

hwndParent Identifies the window that owns the new window. 


This field is NULL if the new window is a top-level 
window. 


Specifies the height of the new window. 


CX 


style 
IpszName 


IpszClass 


DCB 


Specifies the width of the new window. 


Specifies the y coordinate of the upper-left corner of 
the new window. Coordinates are relative to the 
parent window if the new window 1s a child window. 
Otherwise, the coordinates are relative to the screen 
origin. 

Specifies the zcoordinate of the upper-left corner of 
the new window. Coordinates are relative to the 
parent window if the new window is a child window. 
Otherwise, the coordinates are relative to the screen 
origin. 

Specifies the new window’s style. 


Points to a null-terminated character string that 
specifies the new window’s name. 


Points to a null-terminated character string that 
specifies the new window’s class name. 


DCB Communications-Device Control Block 


The DCB structure defines the control setting for a serial communications 


device. 


typedef struct tagDCB { 


BYTE Id 


WORD 
BYTE 
BYTE 
BYTE 
WORD 
WORD 
WORD 


BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 


BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 


BaudRate; 
ByteSize; 
Parity; 
StopBits; 
RlisTimeout: 
CtsTimeout; 
DsrTimeout: 


fBinary: 1; 
fRtsDisable: 1; 
fParity: 1: 


fOutxCtsFlow: 1: 
fOutxDsrFlow: 1: 


fDummy: 2; 
fDtrDisable: 1: 


fOutxX: 1: 
fInX: 1: 
fPeChar: 1: 
fNull: 1: 
fChEvt: 1; 
fDtrFlow: 1: 
fRtsFlow: 1; 
fDummy2: 1: 
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char 
char 
WORD 
WORD 
char 
char 
char 
WORD 
} DCB; 


XonChar: 


XoffChar: 


XonLim: 
XoffLim;: 
PeChar: 
EofChar:; 
EvtChar:; 
TxDelay; 


The DCB structure has the following fields: 


Field 
Id 


BaudRate 


ByteSize 


Parity 


StopBits 
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Description 


Specifies the communication device. This value is _ 
set by the device driver. If the most significant bit 1s 
set, then the DCB structure is for a parallel device. 


Specifies the baud rate at which the communica- 
tions device operates. 


Specifies the number of bits in the characters trans- 
mitted and received. The ByteSize field can be any 
number from 4 to 8, 


Specifies the parity scheme to be used. The Parity 
field can be any one of the following values: 


Value Meaning 


EVENPARITY Even 
MARKPARITY Mark 
NOPARITY No parity 
ODDPARITY Odd 
SPACEPARITY = Space 


Specifies the number of stop bits to be used. The 
ah ious field can be any one of the following 
values: 


Value Meaning 


ONESTOPBIT 1 stop bit 
ONESSTOPBITS 1.5 stop bits 
TWOSTOPBITS 2 stop bits 


Rls Timeout 


Cts Timeout 


Dsr Timeout 


fBinary: 1 


fRtsDisable: 1 


fParity: 1 


fOutxCtsF low: 1 


fOutxDsrF low: 1 


fDtrDisable: 1 


fOutxX: 1 


DCB 


Specifies the maximum amount of time (in milli- 
seconds) the device should wait for the receive-line- 
signal-detect (RLSD) signal. (RLSD is also known as 


the carrier detect (CD) signal.) 


Specifies the maximum amount of time (in milli- 
seconds) the device should wait for the clear-to-send 
(CTS) signal. 


Specifies the maximum amount of time Me milli- 


seconds) the device should wait for the data-set- 
ready (DSR) signal. 


Specifies binary mode. In nonbinary mode, the 
EofChar character is recognized on input and 
remembered as the end of data. 


Specifies whether or not the request-to-send (RTS) 
signal is disabled. If the fRtsDisable field is set, 
RTS is not used and remains low. If fRtsDisable 
is clear, RTS is sent when the device is opened and 
turned off when the device is closed. 


Specifies whether parity checking is enabled. If the 
fParity field is set, parity checking is performed 
and errors are reported. 


Specifies that the clear-to-send (CTS) signal is 

to be monitored for output flow control. If the 
fOutxCtsFlow field is set and CTS is turned off, 
output is suspended until CTS is again sent. 


Specifies that the data-set-ready (DSR) signal is 
to be monitored for output flow control. If the 
fOutxDsrF low field is set and DSR is turned off, 


output is suspended until DSR is again sent. 


Specifies whether the data-terminal-ready (DTR) 
signal is disabled. If the f[DtrDisable field is set, 
DTR is not used and remains low. If {DtrDisable 
is clear, DTR is sent when the device is opened and 
turned off when the device is closed. 


Specifies that XON/XOFF flow control is to be used 
during transmission. If the fOutX field is set, trans- 
mission stops when the XoffChar character is 
received, and starts again when the XonChar char- 
acter Is received. 
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fInX: 1 


fPeChar: 1 


fNull: 1 
fChEvt: 1 


fDtrFlow: 1 


fRtsF low: 1 


XonChar 
XoffChar 


XonLim 


XoffLim 


PeChar 


EofChar 


616 


Specifies that XON/XOFF flow control is to be 
used during reception. If the fInX field is set, the 
XonChar character is sent when the receive queue 
comes within XoffLim characters of being full, and 
the XonChar character is sent when the receive 
queue comes within XonLim characters of being 
empty. 


Specifies that characters received with parity errors 
are to be replaced with the character specified by 
the fPeChar field. The fParity field must be set 
for the replacement to occur. 


Specifies that received null characters are to be dis- 
carded. 


Specifies that reception of the EvtChar character 
is to be flagged as an event. 


Specifies that the data-terminal-ready vars sig- 
nal is to be used for receive flow control. If the 
{DtrF low field is set, DTR is turned off when the 
receive queue comes within XoffLim characters of 
being full, and sent when the receive queue comes 
within XonLim characters of being empty. 


Specifies that the ready-to-send re) signal is to 
be used for receive flow control. If the fRtsF low 
field is set, RTS is turned off when the receive queue 
comes within XoffLim characters of being full, and 
sent when the receive queue comes within XonLim 
characters of being empty. 


Specifies the value of the XON character for both 
transmission and reception. 


Specifies the value of the XOFF character for both 
transmission and reception. 


Specifies the minimum number of characters 
allowed in the receive queue before the XON 
character is sent. 


Specifies the maximum number of characters 
allowed in the receive queue before the XOFF char- 
acter is sent. The XoffLim value is subtracted from 
the size of the receive queue (in bytes) to calculate 
the maximum number of characters allowed. 


Specifies the value of the character used to replace 
characters received with a parity error. 


Specifies the value of the character used to signal 
the end of data. 


DLGTEMPLATE 


EvtChar Specifies the value of the character used to signal 
an event. 
TxDelay Specifies the minimum amount of time that must 


pass between transmission of characters. 


See Also 


The BuildCommDCB, GetCommState, and SetCommState func- 
tions in Chapter 3, “Functions Directory.” 


DLGTEMPLATE Dialog Template 


The DLGTEMPLATE structure is divided into two distinct parts: a 
header and a list of items. The header contains a general description of 
the dialog box; the item list describes the parts that compose the dialog 
box. The CreateDialogIndirect and DialogBoxIndirect functions use 
this structure. The DLGTEMPLATE header is shown here: 


long dtStyle 

BYTE dtItemCount 

int dtX 

int dtY 

int dic 

int dtCy 

char dtResourceName [] 
char dtClassName[] 
char dtCaptionText [] 


The DLGTEMPLATE header has the following fields: 


Field Description 

dtStyle Specifies the style of the dialog box. 

dtitemCount Specifies the number of items in the dialog box. 
dtX Specifies the coordinate of the upper-left corner of 


the dialog box. This value is relative to the origin 
of the parent window’s client area. 


dtY Specifies the y coordinate of the upper-left corner of 
the dialog box. This value is relative to the origin 
of the parent window’s client area. 


dtCX Specifies the extent of the dialog box. 
dtCy Specifies the yextent of the dialog box. 
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dtResourceName| | 
Specifies a zero-terminated string that specifies the 
name of the appleationsresourcetfile. otialog box's ment. 


dtClassName| | Specifies a zero-terminated string that specifies the 


dialog boswdndew’s classname. Fur Staudordt Diabopox thu t-Bykt Nullrhiy . — 


dtCaptionText[] Specifies a zero-terminated string that is used as the 
caption for the dialog box. 


The item list, as shown here, follows the header: 


int dtilxX 

int datilyY 

int dtilCx 

int. Gey ase. of ¥ 2 
int ataliIp , eyo =) 
long atifstyle 

char dtilText 

BYTE dtiliInfo 


The DLGTEMPLATE item list has the following fields: 


Field Description 
dtilX Specifies the acoordinate of the upper-left corner 


of the dialog-box item. This value is relative to the 
origin of the dialog box. 


dtilY Specifies the ycoordinate of the upper-left corner 
of the dialog-box item. This value is relative to the 
origin of the dialog box. 


dtilCX Specifies the 2-extent of the dialog-box item. 
dtilCY Specifies the yextent of the dialog-box item. 
dtilID Specifies the dialog-box item identification number. 
dtilStyle Specifies the style of the dialog-box item. 

dtilText Specifies the text for the item; it is a zero- 


terminated string. 


dtilInfo Specifies the number of bytes of additional data 
that follows this item description and precedes the 
next item description. 
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HANDLETABLE Window-Handle Table 


The HANDLETABLE structure is an array of handles, each containing 
an address of a GDI object and a description of the object. 


HANDLE objectHandle[1} 
The HANDLETABLE structure has the following field: 
Field Description 


objectHandle[1] Identifies an array of handles. 


LOGBRUSH Logical-Brush Attribute Information 

The LOGBRUSH structure defines the style, color, and pattern of a 
physical brush to be created by using the CreateBrushIndirect 
function. 


typedef struct tagLOGBRUSH { 


WORD lbStyle; 

DWORD lbColor: 

short int lbHatch: 
} LOGBRUSH; 


The LOGBRUSH structure has the following fields: 
Field Description 


IbStyle Specifies the brush style. The IbStyle field can be 
any one of the following styles: 


BS_ HATCHED 
BS_ HOLLOW 
BS_ INDEXED 
BS_ PATTERN 
Bs— SOLID 


lbColor Specifies the color in which the brush is to be 
drawn. The lbColor field must be an RGB 
color value. If IbStyle is BS. HOLLOW or 
BS_ PATTERN, IbColor is ignored. 


IbHatch Specifies a hatch style. The meaning depends on the 
brush style. 


LOGBRUSH 


If IbStyle is BS_ HATCHED, the IbHatch field 
specifies the orientation of the lines used to create 
the hatch. It can be any one of the following values: 


Value Meaning 

HS_BDIAGONAL  45-degree downward hatch 
(left to right) 

HS_ CROSS Horizontal and vertical 


cross-hatch 
HS. DIAGCROSS 45-degree cross-hatch 


HS_FDIAGONAL  45-degree upward hatch 
(left to right) 


HS. HORIZONTAL = Horizontal hatch 
HS. VERTICAL Vertical hatch 


If lbStyle is BS_ PATTERN, IbHatch must be a 
handle to the bitmap that defines the pattern. 


If IbStyle is BS_ SOLID or BS. HOLLOW, IbHatch 


is ignored. 


see Also 


The CreateBrushIndirect function in Chapter 3, “Functions Directory.” 


LOGFONT Logical-Font Descriptor 


The LOGFONT structure defines the attributes of a font, a drawing 
object used to write text on a display surface. 


typedef struct tagLOGFONT { 
short int lfHeight; 
short int 1fWidth; 
short int 1fEscapement; 
short int 1fOrientation; 
short int l1fWeight; 


BYTE lfItalic: 

BYTE lfUnderline: 

BYTE LfStrikeOut: 

BYTE 1fCharSet: 

BYTE 1fOutPrecision; 

BYTE l1fClipPrecision; 

BYTE lfQuality; 

BYTE lfPitchAndFamily; 

BYTE 1fFaceName [LF_FACESIZE] ; 
} LOGFONT; 
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The LOGFONT structure has the following fields: 
Field Description 


IfHeight Specifies the average height of the font (in device 
units). The height of a font can be specified in three 
ways: if the IfHeight field is greater than zero, it is 
transformed into device units and matched against 
the cell height of the available fonts; if fHeight is 
zero, a reasonable default size is used; if lfHeight is 
less than zero, it is transformed into device units 
and the absolute value is matched against the char- 
acter height of the available fonts. 


lfWidth Specifies the average width of characters in the font 
(in device units). If the lfWidth field is zero, the 
aspect ratio of the device is matched against the 
digitization aspect ratio of the available fonts for 
the closest match by absolute value of the dif- 
ference. 


If—scapement Specifies the angle (in tenths of degrees) between 
the escapement vector and the zaxis of the display 
surface. The escapement vector is the line through 
the origins of the first and last characters on a line. 
The angle is measured counterclockwise from the 
t- AXIS. 

IfOrientation Specifies the angle (in tenths of degrees) between 


the baseline of a character and the z-axis. The angle 
is measured counterclockwise from the xaxis. 


lfWeight Specifies the font weight (in inked pixels per 1000). 
Although the lfWeight field can be any integer 
value from 0 to 1000, the common values are as 


follows: 
400 Normal 
700 Bold 


These values are approximate; the actual appear- 
ance depends on the font face. If IfWeight is zero, 
a default weight is used. 


IfItalic Specifies an italic font if set to nonzero. 
lfUnderline Specifies an underlined font if set to nonzero. 
lfStrikeOut Specifies a strikeout font if set to nonzero. 
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IfCharSet 


lfOutPrecision 


IfClipPrecision 


IfQuality 
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Specifies the font’s character set, which can be 
either one of the following values: 


ANSIL CHARSET 
OEM_ CHARSET 


The ANSI character set is illustrated in Figure 2.24. 
The OEM character set is system-dependent. 


Specifies the font’s output precision, which defines 
how closely the output must match the requested 
font’s height, width, character orientation, 
escapement, and pitch. The default setting is 
OUT_ DEFAULT _ PRECIS. 


Specifies the font’s clipping precision, which defines 
how to clip characters that are partially outside 
the clipping region. The default setting is 

CLIP... DEFAULT_ PRECIS. 


Specifies the font’s output quality, which defines 
how carefully GDI must attempt to match the 
logical-font attributes to those of an actual physical 
font. It can be any one of the following values: 


Value Meaning 


DEFAULT. QUALITY 
Appearance of the font does not matter. 


DRAFT_ QUALITY 
Appearance of the font is less important 
than when PROOF QUALITY is used. 
For GDI fonts, scaling is enabled, which 
means that more font sizes are available, 
but the quality may be lower. Bold, italic, 
underline, and strikeout fonts are syn- 
thesized if necessary. 


PROOF. QUALITY 
Character quality of the font is more 
important than exact matching of the 
logical-font attributes. For GDI fonts, 
scaling is disabled and the font closest in 
size is chosen. Although the chosen font 
size may not be mapped exactly when 
PROOF_ QUALITY is used, the quality of 
the font is high and there is no distortion 
of appearance. Bold, italic, underline, and 
strikeout fonts are synthesized if neces- 
sary. 


LOGFONT 


IfPitchAndF amily Specifies the font pitch and family. The two low- 
order bits specify the pitch of the font and can be 
any one of the following values: 


DEFAULT_ PITCH 
FIXED. PITCH 
VARIABLE_ PITCH 


The four high-order bits of the field specify the font 
family and can be any one of the following values: 


FF_ DECORATIVE 
FF_DONTCARE 
FF_ MODERN 

FF_ ROMAN 

FF_ SCRIPT 

FF_ SWISS 


The proper value can be obtained by using the 
Boolean OR operator to join one pitch constant 
with one family constant. 


Font families describe the look of a font in a general 
way. They are intended for specifying fonts when 
the exact typeface desired is not available. The 
values for font families are as follows: 


Value Meaning 


FF_ DECORATIVE 
Novelty fonts. Old English, for example. 


FF_ DONTCARE 


Don’t care or don’t know. 


FF_ MODERN 
Fonts with constant stroke width (fixed- 
pitch), with or without serifs. Fixed-pitch 
fonts are usually modern. Pica, Elite, and 
Courier, for example. 


FF_ ROMAN 
Fonts with variable stroke width (pro- 
portionally spaced) and with serifs. Times 
Roman, Palatino, and Century School- 
book, for example. 


FF_ SCRIPT 
Fonts designed to look like handwriting. 
Script and Cursive, for example. 


FF_ SWISS 
Fonts with variable stroke width (pro- 
portionally spaced) and without serifs. 
Helvetica and Swiss, for example. 
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lfFaceName[LF_FACESIZE] 
Specifies the font’s typeface. It must be a null- 
terminated character string. If lfFaceName is 
NULL, GDI uses a default typeface. 


See Also 


The CreateFontIndirect function in Chapter 3, “Functions Directory.” 


LOGPEN Logical-Pen Attribute Information 


The LOGPEN structure defines the style, width, and color of a pen, a 
drawing object used to draw lines and borders. The CreatePenIndirect 
function uses the LOGPEN structure. 


typedef struct tagLOGPEN { 
WORD lopnstyle; 
POINT lopnWidth; 
DWORD lopnColor; 

} LOGPEN; | 


The LOGPEN structure has the following fields: 


Field Description 
lopnStyle Specifies the pen type, which can be any one of the 
following values: 
0 solid = 
1 Dash --- 
2 Dot baa 
3 Dash-dot ae 
4 Dash-dot-dot —.-.. 
3 Null 
lopn Width Specifies the pen wide (in logical units). If the 


lopn Width field is zero, the pen is one pixel wide 
on raster devices. 


lopnColor Specifies the pen color. The lopnColor field must 
be an RGB color value. 


Comments 


The y value in the POINT structure for lopn Width is not used. 
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See Also 


MENUITEMTEMPLATE 


The CreatePenIndirect function in Chapter 3, “Functions Directory.” 


MENUITEMTEMPLATE Menu-Item Template 


One or more MENUITEMTEMPLATE structures are combined to 
form a menu template. 


BYTE mtOption 


WORD mtID 


LPSTR mtString 


The MENUITEMTEMPLATE structure has the following fields: 


Field 


mtOption 


Description 


Specifies a mask of one or more predefined menu 
options that specify the appearance of the menu 
item. The menu options are as follows: 


Value 
CHECKED 


END 


GRAYED 


HELP 


INACTIVE 


MENUBREAK 


MENUBREAKBAR 


POPUP 


Meaning 


Item has a checkmark next 
to it. 


Item must be specified for the 
last item in a pop-up menu or 
a static menu. 


Item is initially inactive and 
drawn with a gray effect. 


Item is a right-justified static 
menu; the keyboard can 
select this item. 


Item name is displayed but 
cannot be selected. 


Item is placed in a new 
column. 


litem is placed in a new 
column. The old and new 
columns are separated by 
a bar. 


Item displays a sublist of 
menu items when selected. 
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mtID Specifies an identification code for a non-pop-up 
menu item. 
mtString Points to a null-terminated character string that 


specifies the name of the menu item. 


See also 


The LoadMenulIndirect function in Chapter 3, “Functions Directory.” 


METAFILEPICT Metafile Picture Structure 


The METAFILEPICT structure defines the metafile picture format used 
for exchanging metafile data through the clipboard. 


typedef struct tagMETAFILEPICT { 
int mm; 
int xExt, yExt; 
HANDLE hWMEF; 

} METAFILEPICT; 


The METAFILEPICT structure has the following fields: 


Field Description 

mm Specifies the mapping mode in which the picture is 
drawn. 

x Ext Specifies the size of the metafile picture for 


all modes except the MM_ ISOTROPIC and 
MM. ANISOTROPIC modes. The zextent spec- 
ifies the width of the rectangle within which the 
picture is drawn. The coordinates are in units 
that correspond to the mapping mode. 


yExt Specifies the size of the metafile picture for 
all modes except the MM. ISOTROPIC and 
MM_ ANISOTROPIC modes. The yextents spec- 
ifies the height of the rectangle within which the 
picture is drawn. The coordinates are in units 
that correspond to the mapping mode. 


For MM. ISOTROPIC and MM. ANISOTROPIC 
modes, which can be scaled, the xExt and 
y Ext fields contain an optional suggested size 
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in MM_ HIMETRIC units. For MM_ ANISOTROPIC 
pictures, xExt and yExt can be zero when no sug- 
gested size is supplied. For MM_ ISOTROPIC pic- 
tures, an aspect ratio must be supplied even when 
no suggested size is given. (If a suggested size is 
given, the aspect ratio is implied by the size.) To 
give an aspect ratio without implying a suggested 
size, set xExt and yExt to negative values whose 
ratio is the appropriate aspect ratio. The magnitude 
of the negative xExt and yExt values will be 
ignored; only the ratio will be used. 


hMF Identifies a memory metafile. 


MSG Message Data Structure 


The MSG structure contains information from the Windows application 
queue. 


typedef struct tagMSG { 
HWND hwnd; 
WORD message; 
WORD wParam: 
LONG 1Param; 
DWORD time; 
POINT pt; 
} MSG; 


The MSG structure has the following fields: 


Field Description 

hwnd Identifies the window that receives the message. 

message Specifies the message number. 

wParam Specifies additional information about the message. 
The exact meaning depends on the message value. 

lParam Specifies additional information about the message. 
The exact meaning depends on the message value. 

time Specifies the time at which the message was posted. 

pt Specifies the position of the mouse (in screen coor- 


dinates) when the message was posted. 
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OFSTRUCT Open-File Structure 


The OFSTRUCT structure contains information about a file which 
results from opening that file. 


typedef struct tagOFSTRUCT f{ 


BYTE cBytes; 
BYTE fFixedDisk:; 


WORD nErrCode; 
BYTE reserved [4]; 
BYTE szPathName [120] ; 


} OFSTRUCT; 


The OFSTRUCT structure has the following fields: 


Field 


cBytes 


fF ixedDisk 


nErrCode 


reserved [4] 
szPathName[120] 


Description 


Specifies the length of the OFSTRUCT structure 
(in bytes). 


Specifies whether the file is on a fixed disk. The 
fFixedDisk field is nonzero if the file is on a fixed 
disk. 


Specifies the DOS error code if the OpenFile func- 
tion returns —1 (that is, OpenFile failed). 


Reserved field. Four bytes reserved for future use. 


Specifies 120 bytes that contain the pathname of 
the file. 


PAINTSTRUCT Windows Paint Information 


The PAINTSTRUCT structure contains information for an application 
that can be used to paint the client area of a window owned by that appli- 


cation. 


typedef struct tagPAINTSTRUCT { 


HDC hdc; 
BOOL fErase:; 


RECT rcPaint; 
BOOL fRestore;> 


BOOL fIncUpdate; 
BYTE rgbReserved [16]; 


} PAINTSTRUCT; 
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The PAINTSTRUCT structure has the following fields: 


Field Description 

hdc Identifies the display context to be used for 
painting. 

fErase Specifies whether the background has been redrawn. 
It has been redrawn if nonzero. 

rcePaint Specifies the upper-left and lower-right corners of 
the rectangle in which the painting is requested. 

fRestore Reserved field. Used internally by Windows. 

fIncUpdate Reserved field. Used internally by Windows. 


rgbReserved[16] —_ Reserved field. A reserved block of memory used 
internally by Windows. 


POINT Point Data Structure 
The POINT structure defines the » and ycoordinates of a point. 


typedef struct tagPOINT { 
int x: 
int y: 

} POINT; 


The POINT structure has the following fields: 


Field Description 

x Specifies the acoordinate of a point. 
y Specifies the y coordinate of a point. 
See Also 


The ChildWindowF romPoint, PtInRect, and WindowFromPoint 
functions in Chapter 3, “Functions Directory.” 
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RECT Rectangle Data Structure 


The RECT structure defines the coordinates of the upper-left and lower- 
right corners of a rectangle. 


typedef struct tagRECT { 
int left; 
int top; 
int right; 
int bottom; 
} RECT: 


The RECT structure has the following fields: 
Field Description 
left Specifies the a-coordinate of the upper-left corner 


of a rectangle. 


top Specifies the ycoordinate of the upper-left corner 
of a rectangle. 


right Specifies the coordinate of the lower-right corner 
of a rectangle. 


bottom Specifies the y coordinate of the lower-right corner 
of a rectangle. 


Comments 


The width of the rectangle defined by the RECT structure must not 
exceed 32K units. 


RGB Logical Color Specification 
DWORD RGB (r,g,b) 


An RGB color value is a long integer that contains a red, a green, and a 
blue color field, each specifying the intensity of the given color. Intensities 
range from 0 to 255. The values are packed in the three low-order bytes of 
the long integer in the following format: 


r+2®°X g+2'°x 6 


The maximum value for a single byte is OFF (hexidecimal); the minimum 
is 0. Black (that is, no color information) corresponds to 0,0,0 (0 in all 
three bytes). White is all color: FF ,FF,FF. Gray is half energy, correspond- 


ing to 7F,7F,7F. Solid green is 00,FF,00. 
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TEXTMETRIC Basic Font Metrics 


The TEXTMETRIC structure contains basic information about a physi- 
cal font. All sizes are given in logical units; that is, they depend on the 
current mapping mode of the display context. 


typedef struct tagTEXTIMETRIC { 
short int tmHeight; 
short int tmAscent; 
short int tmDescent: 
short int tmInternalLeading; 
short int tmExternalLeading; 
short int tmAveCharWidth: 
short int tmMaxCharWidth:; 
short int tmWeight; 


BYTE tmIitalic; 

BYTE tmUnderl ined: 
BYTE tmStruckOut; 

BYTE tmFirstChar: 

BYTE tmLastChar: 

BYTE tmDefaultChar: 
BYTE tmBreakChar: 

BYTE tmPitchAndFamily; 
BYTE tmCharSet: 


short int tmOverhang; 

short int tmDigitizedAspectxX; 

short int tmDigitizedAspectY; 
} TEXTMETRIC; | 


The TEXTMETRIC structure has the following fields: 


Field Description 

tmHeight Specifies the height (ascent + descent) of characters. 

tmAscent Specifies the ascent (units above the baseline) of 
characters. 

tmDescent Specifies the descent (units below the baseline) of 
characters. 


tmInternalLeading Specifies the amount of leading pace) inside the 
bounds set by the tmHeight field. Accent marks 
and other foreign characters may occur in this area. 
The designer may set this field to zero. 
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tmExternalLeading 
Specifies the amount of extra leading (space) that 
the application adds between rows. Since this area 
is outside the font, it contains no marks and will 
not be altered by text output calls in either 
OPAQUE or TRANSPARENT mode. The designer 
may set this field to zero. 


tmAveCharWidth Specifies the average width of characters in the font 
(loosely defined as the width of the letter X). 


tmMaxCharWidth Specifies the width of the widest character in the 


font. 

tm Weight Specifies the weight of the font. 

tmitalic Specifies an italic font if it is nonzero. 

tm Underlined Specifies an underlined font if it is nonzero. 

tmStruckOut Specifies a struckout font if it is nonzero. 

tmFirstChar Specifies the value of the first character defined in 
the font. 

tmLastChar Specifies the value of the last character defined in 
the font. 


tmDefaultChar Specifies the value of the character that will be sub- 
stituted for characters that are not in the font. 


tmBreakChar Specifies the value of the character that will be used 
to define word breaks for text justification. 


tmPitchAndFamily 
Specifies the pitch and family of the selected font. 
The low-order bit is set if the font is variable pitch. 
The four high-order bits designate the font family. 
The tmPitchAndFamily field can be combined 
with the hexadecimal value FO by using the bitwise 
AND operator, and then be compared with the font 
family names for an identical match. For a descrip- 
tion of the font families, see the LOGFONT struc- 
ture, earlier in this chapter. 


tmCharSet Specifies the character set of the font. 
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TEXTMETRIC 


Specifies the per-string extra width that may be 
added to some synthesized fonts. When synthesizing 
some attributes, such as bold or italic, GDI or a 
device may have to add width to a string on both a 
per-character and per-string basis. For example, 
GDI makes a string bold by expanding the intra- 
character spacing and overstriking by an offset 
value; it italicizes a font by skewing the string. In 
either case, there is an overhang past the basic 
string. For bold strings, the overhang is the distance 
by which the overstrike is offset. For italic strings, 
the overhang is the amount the top of the font is 
skewed past the bottom of the font. 


The tmOverhang field allows the application 

to determine how much of the character width 
returned by a Get TextExtent function call on a 
single character is the actual character width and 
how much is the per-string extra width. The actual 
width is the extent minus the overhang. 


tmDigitizedAspectX 


Specifies the horizontal aspect of the device for 
which the font was designed. 


tmDigitizedAspectY 


See Also 


Specifies the vertical aspect of the device for 

which the font was designed. The ratio of the 

tm DigitizedAspectX and tmDigitizedAspect Y 
fields is the aspect ratio of the device for which the 
font was designed. 


The GetDeviceCaps and Get TextMetrics functions in Chapter 3, 
“Functions Directory.” 
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WNDCLASS Window-Class Data Structure 


The WNDCLASS structure contains the class attributes that are 


registered by the RegisterClass function. 


typedef struct tagWNDCLASS { 
WORD 


long 
int 
int 
HANDLE 
HICON 
HCURSOR 
HBRUSH 
LPSTR 
LPSTR 

} WNDCLASS; 


style; 


(FAR PASCAL *lpfnWndProc) (); 


cbClsExtra; 
cbWndExtra; 
hInstance; 
hIcon; 
hCursor: 
hbrBackground; 
lpszMenuName; 
lpszClassName; 


The WNDCLASS structure has the following fields: 


Field 


style 
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Description 


Specifies the class style. These styles can be com- 
bined by using the bitwise OR operator. The style 


field can be any combination of the following values: 


Value Meaning 


CS_ BYTEALIGNCLIENT 
Aligns a window’s client area 
on the byte boundary (in the 
x direction). 


CS. BYTEALIGNWINDOW 
Aligns a window on the byte 
boundary (in the # direction). 


CS... CLASSDC Gives the window class its own 
display context (shared by 
instances). 


CS... DBLCLKS Sends double-click messages to 


a window. 


CS._HREDRAW _ Redraws the entire window if 
the horizontal size changes. 


CS_ NOCLOSE Inhibits the close option on the 


system menu. 


WNDCLASS 


CS. OEMCHARS Is the OEM character transla- 
tion (not used by Windows 
applications). 


CS. OWNDC Gives each window instance its 


own display context. 


Note that although the 

CS. OWNDC style is con- 
venient, it must be used with 
discretion because each display 
context occuples approximately 
800 bytes of memory. 


CS..PARENTDC Gives the parent window’s 
display context of the window 
class. 


CS_SAVEBITS — Saves the window’s bitmap; the 
application can then use the bit- 
map to re-create the original 
window. 


CS. VREDRAW _ Redraws the entire window if 


the vertical size changes. 


IpfnWndProc Points to the window function. 

cbClsExtra Specifies the number of bytes to allocate following 
the window-class structure. 

cbWndExtra Specifies the number of bytes to allocate following 
the window instance. 

hInstance Identifies the class module. The hInstance field 
must be an instance handle and must not be NULL. 

hIcon Identifies the class icon. The hIcon field must be a 


handle to an icon resource. If hIcon is NULL, the 
application must draw an icon whenever the user 
minimizes the application’s window. 


hCursor Identifies the class cursor. The hCursor field must 
be a handle to a cursor resource. If hCursor is 
NULL, the application must explicitly set the 
cursor shape whenever the mouse moves into the 
application’s window. 
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hbrBackground 


IpszMenuName 


IpszClassName 


Identifies the class background brush. The 
hbrBackground field can be either a handle to 

the physical brush that is to be used for painting 
the background, or it can be a color value. Ifa 

color value is given, it must be one of the stan- 

dard system colors listed below, and the value 1 
must be added to the chosen color (for example, 
COLOR BACKGROUND -+ 1 specifies the system 
background color). If a color value is given, it must 
be converted to one of the following HBRUSH types: 


COLOR ACTIVEBORDER 
COLOR_ ACTIVECAPTION 
COLOR_ APPWORKSPACE 
COLOR _ BACKGROUND 
COLOR_ CAPTIONTEXT 
COLOR_ INACTIVEBORDER 
COLOR. INACTIVECAPTION 
COLOR MENU 

COLOR MENUTEXT 
COLOR_ SCROLLBAR 
COLOR_. WINDOW 

COLOR WINDOWFRAME 
COLOR WINDOWTEXT 


When hbrBackground is NULL, the application 
must paint its own background whenever it is 
requested to paint in its client area. The applica- 
tion can determine when the background needs 
painting by processing the WM_ERASEBKGND 
message or by testing the fErase field of the 
PAINTSTRUCT structure filled by the 


BeginPaint function. 


Points to a null-terminated character string 

that specifies the resource name of the class menu 
(as the name appears in the resource file). If an 
integer is used to identify the menu, the 
MAKEINTRESOURCE macro can be used. 

If the lpszMenuName field 1s NULL, windows 


belonging to this class have no default menu. 


Points to a null-terminated character string that 
specifies the name of the window class. 
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File Formats 


7.1 Introduction 


This chapter describes the file formats used to create and execute a Micro- 
soft Windows application. The formats of font files, executable files, and 
the Windows initialization file are described here. 


7.2 Font-File Format 


The standard fonts file provided with Windows, fonts.fon, includes fonts 
for both 2:1 and 1:1 aspect-ratio displays; only the fonts whose aspect 
ratio matches the display are actually used. There are three sizes of fonts 
provided in the ANSI character set: 6, 8, and 11 pixels high for 2:1 dis- 
plays and 12, 16, and 22 pixels high for 1:1 displays. There is only one 1:1 
and one 2:1 OEM-dependent font. There are both terminal and document 
typefaces in each size. 


Windows is capable of synthesizing attributes such as bold, italic, and 

underlining so such fonts are not included in fonts.fon. The fonts that do 
not correspond to the user’s display aspect ratio are nevertheless generic 
raster fonts that can be used for output devices such as bitmap printers. 


Formats for font files are defined for both raster and vector fonts. These 
formats may be used by smart text generators in some GDI support 
modules. ‘The vector formats, in particular, are more frequently used by 
GDI itself than by support modules. 


Both raster and vector font files begin with information that is common to 
both, and then continue with information that differs for each type of file. 

Font files are stored with an .fné extension of the form name.fnt. The infor- 
mation at the beginning of both types of files is shown in the following list: 


Field Description 
dfVersion Two bytes. Specifies the version of the file. ( Bole Swopped 4 ) 
dfSize Four bytes. Specifies the total size of the file 
(in bytes). 
dfCopyright Sixty bytes. Specifies copyright information. 
dfType Two bytes. Specifies the type of font file. The low- 


order byte is for GDI use exclusively. If the low- 
order bit of the word is zero, it is a bitmap (raster) 
font file. [f the low-order bit is 1, it is a vector font 
file. The second bit is reserved and must be zero. 
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dfPoints 


dfVertRes 


dfHorizRes 


dfAscent 


dfInternalLeading 


dfExternalLeading 


dfItalic 


dfUnderline 
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If no bits follow in the file and the bits are located 
in memory at a fixed address specified by the 
dfBitsOffset field, the third bit is set to 1; other- 
wise, the bit is set to zero. The high-order bit of 
the low-order byte is set if the font is chosen by a 
device. The remaining bits in the low-order byte 
are reserved and set to zero. 


The high-order byte is reserved for device use and 
will always be set to zero for GDI-chosen standard 
fonts. Physical fonts with the high-order bit of the 
low-order byte set may use this byte to describe 
themselves. GDI never inspects the high-order byte. 


Two bytes. Specifies the point size at which the 
specified character set looks best. 


Two bytes. Specifies the vertical resolution (dots 
per inch) at which the specified character set was 
digitized. 

Two bytes. Specifies the horizontal resolution (dots 
per inch) at which the specified character set was 
digitized. 

Two bytes. Specifies the distance from the top of a 
character-definition cell to the baseline of the font, 


for aligning the baselines of fonts of different 
heights. 


Two bytes. Specifies the amount of leading (space) 
inside the bounds set by the dfPixHeight field. 
Accent marks and other foreign characters may 
occur in this area. The designer may set this field 
to zero. 


Two bytes. Specifies the amount of extra leading 
space) that the application adds between rows. 
ince this area 1s outside of the font proper, it con- 

tains no marks and will not be altered by text- 

output calls in either OPAQUE or TRANSPARENT 
mode. The designer may set this field to zero. 


One byte. Specifies whether the character-definition 
data represent an italic font. The low-order bit is 1 
if the flag is set. All other bits are zero. 


One byte. Specifies whether the character-definition 
data represent an underlined font. The low-order bit 
is 1 if the flag is set. 


dfStrikeOut 


dfWeight 


dfCharSet 


dfPix Width 


dfPixHeight 


dfPitchAndF amily 
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One byte. Specifies whether the character-definition 
data represent a struckout font. The low-order 
bit 1s 1 if the flag is set. All other bits are zero. 


Two bytes. Specifies the weight of the characters in 
the character-definition data, on a scale from 1 to 
1000. A dfWeight field of 400 specifies a regular 
weight. 


One byte. Specifies the character set defined by this 
font. 


Two bytes. Specifies width. For vector fonts, the 
dfPix Width field specifies the width of the grid on 
which the font was digitized. For raster fonts, if 
dfPix Width is nonzero, it represents the width for 
all characters in the bitmap; if dfPix Width is zero, 
the font has variable-width characters whose widths 
are specified by the dfCharOffset array. 


Two bytes. Specifies the height of the character 
bitmap (raster fonts), or the height of the grid 
on which a vector font was digitized. 


One byte. Specifies the pitch and font family. The 
low-order bit is set if the font is variable-pitch. The 
four high-order bits give the font family name. Font 
families describe the look of a font in a general way; 
they specify fonts when the exact typeface name 
desired is not available. The values for font families 
are as follows: 


Value Meaning 


FF_. DECORATIVE (5< <4) 
Novelty fonts. Old English, 
for example. 


FF_ DONTCARE a 

eneric family name. Used 
when information about a 
font does not exist or does 
not matter. 


FF_ MODERN (3< <4) : 

Fonts with constant stroke 
width (fixed-pitch), with or 
without serifs. Fixed-pitch 
fonts are usually modern. 
Pica, Elite, and Courier, 
for example. 
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dfAvgWidth 


dfMax Width 


dfFirstChar 


dfLastChar 


dfDefaultChar 


dfBreakChar 
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FF_ROMAN (1<<4) Fonts with variable stroke 
width (proportionally 
spaced), with serifs. Times 
Roman, Palatino, and 
Century Schoolbook, for 
example. 


FF_SCRIPT (4<<4) Fonts designed to look like 
handwriting. Script and 
Cursive, for example. 


FF_SWISS (2<<4) Fonts with variable stroke 
width (proportionally 
spaced) without serifs. 
Helvetica and Swiss, for 
example. 


Two bytes. Specifies the width of characters in the 
font. For fixed-pitch fonts, this is the same as the 
dfPix Width field. For variable-pitched fonts, this 
is loosely defined as the width of the character X. 


Two bytes. Specifies the maximum pixel width of 
any character in the font. For fixed-pitch fonts, this 
is the same as dfPix Width. 


One byte. Specifies the first character code defined 
by this font. Character codes are stored only for 
thecharacters actually present in a font, so the 
dfFirstChar field should be used when calculat- 
ing indexes into either the dfBitsOffset or 
dfCharOffset fields. 


One byte. Specifies the last character code defined 
by this font. Note that all characters with codes 
between dfFirstChar and dfLastChar must be 
present in the font character definitions. 


One byte. Specifies the character to substitute 
whenever a string contains a character out of the 
dfFirstChar through dfLastChar range. The 
character is given relative to dfFirstChar so that 
dfDefaultChar is the actual value of the char- 
acter minus the value of dfFirstChar. The 
dfDefaultChar field should indicate a special 
character in the font that is not a space. 


One byte. Specifies the character which will define 
word breaks. This character defines word breaks for 
wordwrapping and word-spacing justification. The 


dfWidthBytes 


dfDevice 


dfF'ace 


dfBitsPointer 


dfBitsOffset 


CharTable 
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character is given relative to dfFirstChar so that 
the dfBreakChar field is the actual value of the 
character minus the value of dfFirstChar. The 
dfBreakChar field is normally 32 — dfFirstChar 
(an ASCII space). 


Two bytes. Specifies the number of bytes in each 
row of the bitmap. This is always an even number, 
so that the rows start on word boundaries. For 
vector fonts, this field has no meaning. 


Four bytes. Specifies the offset in the file to the 
string that gives the device name. For a generic 
font, this value is zero. 


Four bytes. Specifies the offset in the file to the 
null-terminated character string that names the 
typeface. 


Four bytes. Specifies the absolute address of the 
bitmap. This is set by GDI at load time. The 
dfBitsPointer field must be even. 


Four bytes. Specifies the offset in the file to the 
beginning of the bitmap information. If the 04H bit 
in the dfType field is set, then the dfBitsOffset 
field is the absolute address of the bitmap. For 
raster fonts, dfBitsOffset points to a sequence of 
bytes that make up the bitmap of the font, whose 
height is the height of the font, and whose width is 
the sum of the widths of the characters in the font 
rounded up to the next word boundary. For vector 
fonts, dfBitsOffset points to a string of bytes or 
words (depending on the size of the grid on which 
the font was digitized) that specifies the strokes for 
each character of the font. The dfBitsOffset field 
must be even. 


The number of bytes depends on the particular 
character set. For raster fonts, the CharTable field 
is an array of entries, each consisting of two two- 
byte words. The first word of each entry is the char- 
acter width. The second word of each entry is the 
byte offset from dfType to the character bitmap. 


There is one extra entry, a spare, at the end of this 
array that describes the absolute-space character. 
This entry corresponds to a character which is 
guaranteed to be blank; it is not part of the normal 
character set. 
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<facename> 


<“devicename > 


< bitmaps > 
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The number of entries in the array is calculated as 
((dfLastChar — dfFirstChar) + 2). This includes 
the spare, the sentinel offset mentioned in the next 
paragraph. 


For fixed-pitch vector fonts, each two-byte entry in 
this array specifies the offset from the start of the 
bitmap to the beginning of the string of stroke- 
specification units for the character. The number of 
bytes or words to be used for a particular character 
is calculated by subtracting its entry from the next 
one, so that there is a sentinel at the end of the 
array of values. 


For proportionally spaced vector fonts, each four- 
byte entry is divided into two two-byte fields. The 
first field gives the starting offset (from the start of 
the pine?) of the character strokes, in the same 
manner as for fixed-pitch fonts. The second field 
gives the pixel width of the character. 


The number of bytes depends on the size of the 
character string that specifies the name of the 
typeface. The size of this field is the length of the 
string plus a null terminator. 


The number of bytes depends on the size of the 
character string that specifies the name of the 
typeface, or the character string that specifies the 
name of the device, if this font file is for a specific 
device. The size of this field is the length of the 
string plus a null terminator. 


The number of bytes depends on the size of the 
character string that specifies the name of the 
typeface. This field contains the character bitmap 
definitions. Each character is stored as a contiguous 
set of bytes. (In the previous font format, this was 
not the case.) The first byte contains the first eight 
bits of the first scan line (that is, the top line of the 
character). The second byte contains the next eight 
bits of the first scan line, if there are that many. If 
not, the unused bits are cleared to zero. This contin- 
ues until the first scan line is completely defined. 
The following byte contains the first eight bits of 
the second scan line. (Clearly, if the font is eight 
bits wide or less, each scan line is covered by one 
byte, with bits set to zero as necessary for padding.) 
Note that character bitmaps must be stored con- 
tiguously and arranged in ascending order. 
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Figure 7.1 shows the schematic of a 10 X 12 pixel character: 


a ~*. o*, 
o*%-e a4 7X 
Keaea® 


oe Was te Bias 


ee Rese eR es 


Figure 7.1 10 X 12 Pixel Character 


The bytes are given here in pairs, each pair corresponding to one scan line 
(10 pixels and 6 bits of padding): 


0000 OBOO 1200 4100 4100 4100 3FO0O 4100 4100 0000 0000 0000 


Note that the second byte of each pair in this particular case is always 
Zero. 


7.3 Executable-File Header Format 


An executable file contains Windows code and data, or Windows code, 
data, and resources. A header, with information about segment entry 
points, stack offsets, and stack sizes, is added to the beginning of this 
executable file. The loader uses this header information when it loads 
the executable segments in memory. The header is broken into two 
parts: an old-style header and a new-style header. 


7.3.1 Old-Style Header 


The old-style header (WINSTUB) contains information that the loader 
expects for a DOS executable file. It contains a stub program that the 
loader can place in memory when necessary, it points to the new-style 
header, and it contains a relocation table. 
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Figure 7.2 illustrates the four distinct parts of the old-style executable 
header: 


4 
Relocation table | 
NU n progyrarn 
| pos stub eradr: | 


Qid-style header info 


Beginning of 
new-style header 


40k (Offset) 
3CH (Offset) 
26H (Offset) 
BGK (Offset) 


Figure 7.2 WINSTUB—Windows Old-Style Header 


The loader uses the word value at offset 18H in the old-style header to 
determine whether a new-style header follows; if this value is 40H, the 
loader assumes that a new-style header will be found. (This value, 40H, 
is the address of the relocation table.) If a new-style header does exist, 
the long-word value found at offset 3CH in the old-style header gives the 
relative byte offset from the start of the old-style header to the start of 
the new-style header. 


7.3.2 New-Style Header 


Because Windows executable files are often larger than one segment (64K), 
additional information (that doesn’t appear in the old-style header) is 
required so that the loader can properly load each segment. The new-style 
header was developed to provide the loader with this information auto- 
matically. 


Sections 7.3.3 through 7.3.10 describe each of the eight entries in the new- 
style header. Each section contains a description of an entry and informa- 
tion about the various components of an entry in the new-style header. 


7.3.3 New- Style Header Information Block 


The first entry in the new-style header contains general header informa- 
tion, as well as information that Windows copies to the module table. a 
module table contains information that the linker uses for dynamic link- 
ing.) Windows copies the information from location (relative offset) OOH to 
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the end of the information block into the module table. The following list 
describes the general information found in this block; the locations are 
relative to the beginning of the header-information block: 


Location 


OH 


2H 
3H 
4H 


6H 
8H 


CH 


EH 


Content 


Signature word. 
N is the low-order byte. 
E is the high-order byte. 


Version number of the linker. 
Revision number of the linker. 


Offset of the entry table (relative to the beginning 
of the new-style header). 


Number of bytes in the entry table. 


CRC-32 of the entire contents of the file (with 
the subsequent words taken as 00 during the 
calculation). 


Keyword. 


0000H NOAUTODATA 

0001H SINGLEDATA (Solo). — 
0002H MULTIPLEDATA (Instance). 
2000H Errors detected at link time. 
8000H Library module. 


The 88:SP information is invalid and CS:IP points to an 
initialization procedure called with AX equal to the module 
handle. This initialization procedure must execute a far 
return to the caller, with AX not equal to zero indicating 
success and AX equal to zero indicating failure to initialize. 
DS is set to the library’s data segment if the SINGLEDATA 
keyword is set. Otherwise, DS is set to the caller’s data seg- 
ment. 


Only executable programs that have their SINGLEDATA 
keyword set may be dynamically linked. If SINGLEDATA is 
set, MULTIPLEDATA must be cleared. 


Segment number of the automatic data segment (index into 
the segment table). 


EH is set to zero if the SINGLEDATA and MULTIPLE- 
DATA bits are cleared. 
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10H 


12H 


14H 
18H 


32H 
34H 
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Initial size (in bytes) of the dynamic heap added to the data 
segment. This word equals zero if there is no local alloca- 
tion. 


Initial size (in bytes) of the stack added to the data seg- 
ment. This word equals zero if SS does not equal DS. 


Segment number:offset of CS:IP. 
Segment number:offset of SS:SP. 


Segment number is an index into the module’s segment 
table. 


The first entry in the segment table is segment number 1. 


If SS equals the automatic data segment and SP equals 
zero, the stack pointer is set to the top of the automatic 
data segment, just below the additional heap area. 


Number of entries in the segment table. 
Number of bytes in the nonresident-name table. 


Offset of the segment table, relative to the beginning of the 
new .eze header. . 


Offset of the resource table, relative to the beginning of the 
new_eze header. 
ee end 


Offset of the resident-name table, relative to the beginning 
of the new .eze header. 
Dew Sees 


Offset of the module-reference table, relative to the begin- 
ning of the new .eze header. 


Offset of the imported-names table, relative to the begin- 
ning of the new .eze header. 
ee 


Offset of the nonresident-name table, relative to the begin- 
ning of the file. 


Number of movable entry points. 


Shift count of the logical-sector alignment, log (base 2) of 
the segment sector size (default 9). 


Number of reserved segments. 
10 dup (0) reserved. 
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7.3.4 Segment Table 


The segment table contains entries for each segment in the executable file. 
The following subentries appear within each entry; their locations are rela- 
tive to the beginning of the entry: 


Location 


OH 


2H 


4H 


6H 


Description 


Logical-sector offset (n byte) to the contents of the 
segment data, relative to the beginning of the file. 
Zero means no file data. 


Length of the segment in the file (in bytes). Zero 
means 64K. 


Keyword. 


0000H CODE Code-segment type. 
0001H DATA Data-segment type. 
0007H TYPE. MASK Segment-type field. 
0010H MOVEABLE Segment is not fixed. 


0040H PRELOAD Segment will be preloaded; 
read-only if this is a data segment. 


0100H RELOCINFO Set if segment has relo- 


cation records. 
FO00H DISCARD Discard priority. 


Minimum allocation size of the segment (in bytes). 
Total size of the segment. Zero means 65,536. 


7.0.9 Resource Table 


The resource table follows the segment table and contains entries for each 
resource in the executable file. The following list describes the subentries 
within each resource entry; their locations are relative to the beginning of 


the entry: 
Location 


OH 
2H 


Description 


Alignment shift count for resource data. 


Type ID: it is integer type if the high-order bit is set 
(8000H); otherwise, it is the offset to the type string, 
relative to the beginning of the resource table. If the 
type ID equals zero, it marks the end of the resource 
records. 
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4H Number of resources for this type. 
6H Reserved. 

_———— Number of resources /copies of the resource entry. 
AH Offset to the contents of the resource data, relative 


to the beginning of the file; the offset is in terms of 
alignment units specified at the beginning of the 


resource table. wes Peal, 


Length of the resource in the file (in bytes). 


Keyword. —— 
0010H MOVEABLE Resource is not fixed. 
0020H PURE Resource can be shared. 

0040H PRELOAD Resource is preloaded. 


Resource ID. It is integer type if the high-order bit 
is set (SOOOH); otherwise, it is the offset to the 
resource string, relative to the beginning of the 
resource table. 


Reserved. 


Resource type and name strings are stored at the 
end of the resource table. Note that these strings 
are not null-terminated. 


16H Length of type or name; equals zero if end of 
resource table. 


17H Text of type or name; case-sensitive. 


7.3.6 Resident-Name Table 


The resident-name table follows the resource table, and contains module 
names. Strings in the resident-name table are case-sensitive; they are not 
null-terminated. The following list describes the subentries and their loca- 
tions with respect to the beginning of each entry: 


Location Description 

00H Length of string. This byte equals zero if there are 
no more strings in the table. 

01H to XXH Text of character string. 

XX + 1H Ordinal number (index into entry table). 
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7.3.7 Module-Reference Table 


The module-reference table follows the resident-name table. Each entry 
contains an offset for the module-name string within the imported-names 
table; each entry is two bytes long. 


7.3.8 Imported-Name Table 


The imported-name table follows the module-reference table. This table 
contains the names of modules that were imported by the executable file. 
Each entry is composed of a one-byte field that contains the length of the 
string, followed by any number of characters. The strings are noé null- 
terminated. 


7.3.9 Entry Table 


The entry table follows the imported-name table. This table contains 
bundles of entry-point ordinal values. (The ordinal value of the first entry 
point is the number 1.) The loader scans the bundles, searching for a 
specific entry point and, upon finding the entry point, multiplies that 
point’s ordinal value by the entry size in order to index the entry properly. 


The linker forms bundles in the most dense manner it can, under the 
restriction that 1t cannot reorder entry points to improve bundling. 
The reason for this restriction is that other .eze files may refer to entry 
points within this bundle by their ordinal value, as described in the 
following table: 


Location Description 


OH Number of entries in this bundle. All records in one bun- 
dle are either movable or refer to the same fixed segment. 
This byte equals zero if there are no more bundles in the 
entry table. 


1H Segment indicator for this bundle. 
000 Unused. 


OFFH Movable segment; segment number is in the 
six-byte entry shown im following list: 


DB ~~ Keyword. 
0000 0001 Set if the entry is exported. 


0000 0010 Set if the segment uses 
shared data segments. 
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INT 
DB 
DW 


3FH. 
Segment number. 


Offset. 


Other—-Segment number of the fixed segment. 
If this is a fixed segment, the entries are three 


bytes: 
DB 


DW 


Keyword. 
0000 0001 Set if the entry is exported. 


0000 0010 Set if the entry uses a glo- 
bal (shared) data segment. 


The following assembly-language 
instruction must be the first instruc- 
tion in the prologue of this entry: 


MOV AX, DS-value 
This may be set only for SINGLEDATA 
library modules. 


Offset. 


7.3.10 Nonresident-Name Table 


The nonresident-name table follows the entry table. The first entry 

in a nonresident-name table is a module description. Strings in the 
nonresident-name table are case-sensitive and are not null-terminated. 
Each entry in the table is of variable size. The following list describes 
the subentries and their locations with respect to the beginning of 


each entry: 

Location Description 

00H Length of string. This byte equals zero if there are 
| no more strings in the table. 

01H to XXH Text of character string. 

XX + 1H Ordinal number (index into entry table). 
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7.4 Windows Initialization File 


The Windows initialization file is a list of application names and option 
values that applications can access while executing. The Windows initiali- 
zation file defines the initial values the user wants application-specific 
options to have. Each option has a corresponding keyname and value. 


The Windows initialization file is kept in a special control file, named 
win.int, that Windows searches for in the Windows boot directory (the cur- 
rent working directory at the time the user calls Windows). If win.in? is 
not found in the boot directory, Windows searches the directories given in 
the PATH environment variable, stopping at the first win.ini file it finds. 
When Windows finds the file, it reads its contents and performs the 
specified actions. 


The win.ini file is an ordinary text file that you can create by using a text 
editor. It has the following form: 


nee name| 
eyname = value 


In this example, [application name] is the name of an application (usually 

the filename of the module file that contains the application). The enclos- 
ing brackets (| |) are required. The keyname = value statement is a special 
line that defines the value of specific options associated with the applica- 

tion. 


You can also place comments in the file. A comment may be placed on any 
line in which the first nonspace character is a semicolon (;). 


Applications can also access and change settings in win.ini during a Win- 
dows session. However, since win.ini is shared by all Windows applications, 
any application that makes a change to sections of win.int that could affect 
other applications must notify other applications of that change by using 
the WM. WININICHANGE message. 


You can give any number of application names. Each name can be fol- 
lowed by one or more keyname-and-value lines. A keyname-and-value line 
that appears immediately below an application name belongs to that 
application. 
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A keyname is the name of an option: It can consist of any combination of 
letters and digits, and must be followed immediately by an equal sign (=). 
A value is the option’s value. It can be any one of the following values: 


Value Description 
Integer Must use decimal digits. 
String Can be any combination of letters, digits, and punctua- 


tion marks; leading spaces are ignored. 


Quoted string Can be any combination of letters, digits, and punctua- 
tion marks, but must be enclosed in double quotation 
marks; spaces within the quotation marks are not 
ignored, and a pair of quotation marks (“”) in the 
string is treated as a single mark. 


Sections 7.4.1 through 7.4.8 describe the subsections of the Windows ini- 
tialization file that are added to win.int by Windows or the control panel. 


7.4.1 Windows Section 
Syntax 


[windows] 

Run =list 

Load = (ist 

Device = output-device-name, device-driver, port-connection 
DeviceNotSelectedTimeout —seconds 
TransmissionRetry Timeout seconds 
DoubleClickSpeed = milliseconds 
xMouseThreshold = mouse units 
yMouseThreshold = mouse units 

MouseSpeed —=n-factor 

CursorBlinkRate = milliseconds 

NullPort = nuil-portname 

Beep == beep-option 

Border Width = width of the border in logical units 


The windows section contains optional settings that take effect when 
Windows is first called. The Run and Load fields tell Windows to load a 
particular application or applications when Windows is first started. The 
list option is a list of one or more application filenames, separated by 
commas or spaces. 
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The Run field must not contain the name of a bad application. A bad 
application 1s any non- Windows application that requires Windows to 
exit from memory before it can run. Placing a bad application in this 

field causes Windows to enter an endless loop. 


All applications listed in the Load line are run and placed in the icon area 
when Windows is first started. All applications listed in the Run line are 
run and displayed as windows when Windows is first started. 


The Device field defines the default output device. This is the device used 
for all printer output if no explicit device is given. The output-device-name 
option can be any device name given in the devices section. An explicit 
port and driver must be assigned to the device. The user can set the 
printer mode in the control panel. The device-driver option is the module 
name (that is, the filename without the extension) of the device-driver file. 
The poré-connection option is any port name given in the ports section. 


The spooler uses the DeviceNotSelected Timeout field to determine the 
number of seconds it will wait for a device to be switched on. If the device 
is not switched on during this time, the spooler posts a message box stat- 

ing that it cannot print to a device. 


Note that for some devices, the spooler immediately posts an error mes- 
sage if the device is not already switched on. 


The DeviceNotSelectedTimeout default value is 15 seconds. The 
spooler uses the TransmissionRetry Timeout field to determine the 
amount of time allowed for attempted transmission retries. If a success- 
ful transmission does not occur during this time, the spooler posts a 
message box stating that the printer is not receiving characters. The 
TransmissionRetry Timeout default value is 45 seconds. 


The DoubleClickSpeed field sets the system’s double-click speed (in 
milliseconds). 


Windows uses a vertical and horizontal MouseThreshold to determine 
the speed of mouse-pointer movement. The xMouseThreshold field is 
the maximum number of mouse units (in the 2 direction) that the mouse 
can move between mouse interrupts before Windows alters the relation- 
ship between mouse movement and mouse-pointer movement. The 
yMouseThreshold field is the maximum number of mouse units (in the 
y direction) that the mouse can move between mouse interrupts before 
Windows alters the relationship between mouse movement and mouse- 
pointer movement. Initially, the mouse pointer moves one unit for each 
unit that the mouse moves. If the mouse movement exceeds either thresh- 
old, Windows causes the mouse pointer to move 2” units for every unit 
that the mouse moves (where nis the MouseSpeed). The MouseSpeed 
default value is one. 
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The CursorBlinkRate field sets the blinking rate (in milliseconds) for the 
system cursor. 


The Beep field enables or disables the MessageBeep function. It is either 
YES or NO, with a default value of YES. Setting this field to NO disables 
the MessageBeep function. 


The NullPort field sets the name used for a null port to null-portname. 
This name is used by the control panel and spooler (and other applica- 
tions) in cases where a device is installed (that is, the device driver is 
present) but is not connected to any port. 


The : alia field contains the width of the border (in logical 
units). 


7.4.2 Debugging Section 
Syntax 


({kernel] 

EnableHeapChecking —heap-checking option 
FnableSegmentChecksum =segment-checksum option 
EnableFreeChecking =/free-checking option 
FreezeGlobalMotion = global-motion option 


The Debugging section contains optional settings that affect the debug- 
ging version of Windows. While these options lower system performance, 
they considerably enhance the debugging process. 


The EnableHeapChecking option is either zero or one. The default 
value is zero. When this option is enabled, Windows verifies that local and 
global heaps are properly linked and that handles point to appropriate 
objects. Windows checks the local heap when an application makes local 
memory calls. Windows checks the global heap when an application makes 
global memory calls. 


If a fatal error occurs, it indicates that the application has improperly 
linked or that the handles do not point to appropriate objects. 


The EnableSegmentChecksum option is either zero or one. The default 
value is one. When this option is enabled, Windows verifies that code seg- 
ments have not been altered by random memory overwrites when the code 
segments are moved or discarded. 


The EnableFreeChecking option is either zero or one. The default value 


is zero. When this option is enabled, Windows uses the CC hexadecimal 
value to initialize all of memory. Whenever an application allocates free 
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memory, Windows verifies that it still contains CC hexadecimal values. 
When an application frees an object, the memory containing that object 
is initialized with CC hexadecimal values. 


The FreezeGlobalMotion option is either zero or one. The default value 
is zero. When this option is enabled, Windows prevents the movement of 
segments in memory. 


7.4.3 Ports Section 
Syntax 


[ports] 
portname:= baud-rate, parity, word-length, stop-bits |,p] 


The ports section lists all available communications ports and defines 
default modes or settings. The portname option must be the name of the 
communications port as it is recognized by DOS. 


The baud-rate setting gives the port’s baud rate. 

The parity setting is 0, e, or n, for odd, even, or none, respectively. 
The word-length setting gives the length of a word (in bits). 

The stop-biés setting gives the number of stop bits to be used. 


The p option is the retry option, which specifies that hardware hand- 
shaking is in effect. 


7.4.4 Colors Section 
Syntax 


[colors] 
component=redvalue greenvalue bluevalue 


The colors section defines the background color for the specified com- 
ponent of the Windows display screen. The component option can be any 
one of the following values: 


Option Definition 

Scrollbar Scroll bar 

Background Icon area and screen background 
ActiveTitle Active caption bar 

Inactive Title Inactive caption bar 
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ActiveBorder Active window’s border 

InactiveBorder Inactive window’s border 

App Workspace Background workspace for multiple document 
interface (MDI) applications 

Menu Menu background 

Window Window client-area background 

AppWorkSpace Application workspace 

WindowF rame Title-bar background and frame color 

MenuText Menu text 

WindowText Window text 

TitleText Title-bar text 


The redvalue setting is an integer that specifies the intensity of red in the 
background. It can be any value from 0 to 255. The greenvalue setting is 
an integer that specifies the intensity of green in the background. It can be 
any value from 0 to 255. The bluevalue setting is an integer that specifies 
the intensity of blue in the background. It can be any value from 0 to 255. 


Windows expects a solid color for the menu (MenuText), window 
(WindowText), title text (TitleText), frame (WindowF rame), 
menu background (Menu), and window background (Window). The 
aaa function can be used to obtain the nearest system 
color. 


7.4.5 Devices Section 


Syntax 


[devices] 
device-name==driver-name, port-name |, portname...| 


The devices section names the output devices that can be accessed by 
Windows device drivers and specifies the communications port or ports to 
which the devices are connected. If a device is not currently connected, the 
port-name setting should be the string specified in the NullPort field of 
the windows section of win.int. 
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7.4.6 Fonts Section 
Syntax 


[fonts] 
font-name==font-file 


The fonts section describes one or more font files that are loaded by Win- 
dows when it is booted. The font-name option is the descriptive name of a 
font. The font-file setting is the filename, without the extension, of a file 
that contains font resources. 


An application can use the EnumFonts function to obtain information 
about the currently available fonts. 


7.4.7 International Section 
Syntax 


[intl] 
wtemname== value 


The intl section describes how to display dates, times, currency amounts, 
and other items for countries other than the United States. Windows does 
not require the intl section in U.S. versions of win.int. Any application 
that uses the intl section must supply its own default value when calling 
the GetProfileString function to retrieve a value from this section. 


The itemname and corresponding value options can be any of the following 
values: 


Option Definition 

iCountry Country Code (for more information, see your DOS 
manual) 

iDate 0 for month-day-year 


1 for day-month-year 
2 for year-month-day 


iCurrency 0 for currency-symbol prefix, no separation 
1 for currency-symbol suffix, no separation 
2 for currency-symbol prefix, one-character separation 
3 for currency-symbol suffix, one-character separation 


iDigits Number of significant decimal digits in currency 


iTime O for 12-hour clock 
1 for 24-hour clock 
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iLzero O for no leading zeros 

1 for leading zeros 
s1159 Trailing string from 0:00 to 11:59 
s2359 Trailing string from 12:00 to 23:59 


sCurrency Currency-symbol string 


sThousand Thousands-separator string 


sDecimal Decimal-separator string 
sDate Date-separator string 
sTime Time-separator string 
sList List-separator string 


7.4.8 Extensions 
Syntax 


[extensions] | 
filename-ertension= executable-filename tnput-filename 


The extensions section is a list of filename extensions and corresponding 
applications that are called when the user double-clicks a file that has one 
of the given extensions. 


The filename-extension option is a one- to three-character extension; the 
executable-filename setting is the filename (with .eze) of the corresponding 
application; the input-filename setting is the filename that will be passed 
to the application when called. The :nput-filename setting can be any 
filename, or it can consist of the special wildcard character, the caret (*), 
followed by a filename extension. The caret (*) represents the filename 
part of the file that the user double-clicks. | 
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Binary and Ternary Raster-Operation Codes and Definitions 


A.1 Introduction 


This appendix describes and lists the binary and ternary raster operations 
used by GDI. A binary raster operation uses two operands: a pen and a 
destination bitmap. A ternary raster operation uses three operands: a 
source bitmap, a brush, and a destination bitmap. Both binary and ter- 
nary raster operations use Boolean operators. 


A.2 Binary Raster Operations 


This section lists the binary raster-operation codes used by the GetROP2 
and SetROP2 functions. Raster-operation codes define how GDI combines 
the bits from the selected pen with the bits in the destination bitmap. 


Hach raster-operation code represents a Boolean operation in which the 
selected pen and the destination bitmap are combined. There are two 
operands used in these operations: 


P Selected pen 
D Destination bitmap 


The Boolean operators used in these operations are as follows: 


O Bitwise OR 

x Bitwise Exclusive OR (XOR) 
a Bitwise AND 

n Bitwise NOT (inverse) 


All Boolean operations are presented in reverse Polish notation. For exam- 
ple, the following operation replaces the destination with a combination of 
the pen and the selected brush: 


DPo 
Each raster-operation code is a 32-bit integer value whose high-order word 


is a Boolean operation index and whose low-order word is the operation 
code. The 16-bit operation index is a zero-extended 8-bit value that 
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represents the result of the Boolean operation on predefined pen and 
destination values. For example, the operation indexes for the DPo and 
DPan operations are shown in Figure A.1: 


DPo DPan 
0 1 
1 1 
1 1 
1 0 


Figure A.1 Operation Indexes for DPo and DPan 


The following list outlines the drawing modes and the Boolean operations 


that they represent: 
Raster Operation 


R2_ BLACK 

R2_ COPYPEN 

R2_. MASKNOTPEN 
R2_ MASKPEN 

R2_. MASKPENNOT 
R2_ MERGENOTPEN 
R2_ MERGEPEN 

R2_ MERGEPENNOT 
R2_ NOP 

R2_ NOT 

R2_ NOTCOPYPEN 
R2_. NOTMASKPEN 
R2_ NOTMERGEPEN 
R2_ NOTXORPEN 
R2_ WHITE 

R2_ XORPEN 
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When a monochrome device is used, GDI maps the value zero to black and 
the value 1 to white. Given an application that attempts to draw with a 
black pen on a white destination by using the available binary raster 


operations, the following results will occur: 


Raster Operation 


R2_ BLACK 

R2_. COPYPEN 

R2_ MASKNOTPEN 
R2_. MASKPEN 

R2_ MASKPENNOT 
R2_ MERGENOTPEN 
R2_ MERGEPEN 

R2_ MERGEPENNOT 
R2_. NOP 

R2_.NOT 

R2_ NOTCOPYPEN 
R2_. NOTMASKPEN 
R2_. NOTMERGEPEN 
R2_ NOTXORPEN 
R2_ WHITE 

R2_ XORPEN 


Result 


Visible black line 
Visible black line 
No visible line 

Visible black line 
Visible black line 
No visible line 

Visible black line 
Visible black line 


No visible line 


Visible black line 


No visible line 
No visible line 
Visible black line 
Visible black line 
No visible line 


No visible line 


When a color device is used, GDI uses RGB values to represent the colors 
of the pen and the destination. An RGB color value is a long integer that 
contains a red, a green, and a blue color field, each specifying the intensity 
of the given color. Intensities range from 0 to 255. The values are packed 
in the three low-order bytes of the long integer. The color of a pen is 
always a solid color, but the color of the destination may be a mixture of 
any two or three colors. Given an application that attempts to draw with 
a white pen on a blue destination by using the available binary raster 
operations, the following results will occur: 


Raster Operation Result 


R2_ BLACK 
R2_ COPYPEN 
R2_ MASKNOTPEN 


Visible black line 
Visible white line 
Visible black line 
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R2.. MASKPEN Invisible blue line 
R2.. MASKPENNOT Visible red/green line 
R2_. MERGENOTPEN Invisible blue line 
R2_. MERGEPEN Visible white line 
R2_. MERGEPENNOT Visible white line 
R2_. NOP Invisible blue line 
R2_ NOT Visible red/green line 
R2_. NOTCOPYPEN Visible black line 
R2_ NOTMASKPEN Visible red/green line 
R2_ NOTMERGEPEN Visible black line 
R2_ NOTXORPEN Invisible blue line 
R2_ WHITE Visible white line 
R2_ XORPEN Visible red/green line 


A.3 Ternary Raster Operations 


This section lists the ternary raster-operation codes used by the BitBlt, 
PatBlt, and StretchBlt functions. Ternary raster-operation codes define 
how GDI combines the bits in a source bitmap with the bits in the destina- 
tion bitmap. 


Each raster-operation code represents a Boolean operation in which the 
source, the selected brush, and the destination bitmap are combined. 
There are three operands used in these operations: 


S Source bitmap 
P Selected brush (also called pattern) 
D Destination bitmap 


The Boolean operators used in these operations are as follows: 


) Bitwise OR 

x Bitwise Exclusive OR (XOR) 
a Bitwise AND 

n Bitwise NOT (inverse) 
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All Boolean operations are presented in reverse Polish notation. For exam- 
ple, the following operation replaces the destination with a combination of 
the source and brush: 


PSo 


The following operation combines the source and brush with the desti- 
nation note that there are alternate spellings of the same function, so 
will be} a particular spelling may not be in the list, an equivalent form 
will be): 


DPSoo 


Each raster-operation code is a 32-bit integer value whose high-order word 
is a Boolean operation index and whose low-order word is the operation 
code. The 16-bit operation index is a zero-extended 8-bit value that rep- 
resents the result of the Boolean operation on predefined brush, source, 
and destination values. For example, the operation indexes for the PSo 
and DPSoo operations are shown in Figure A.2: 


D 


PS PSo ~~ DPSoo 
000 0 0 
001 0 1 
010 1 1 
O11 1 1 
100 1 1 
101 1 1 
110 1 1 
111 ] if 


Operation index: OOFC OOFE 
Figure A.2 Operation Indexes for PSo and DPSoo 


In this case, PSo has the operation index OOFC (read from the bottom 
up); DPSoo has the operation index OOFE. These values define the location 
of the corresponding raster-operation codes, as shown in Table A.1. The 
(hes 7 is in line 252 (hex FC) of the table; DPSoo is in line 254 

ex : 


The most commonly used raster operations have been given special names 
in the Windows include file, windows.h. You should use these names when- 
ever possible in your applications. 
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When the source and destination are monochrome, a bit value of zero rep- 
resents a black pixel and a bit value of 1 represents a white pixel. When 
the source and the destination are color, those colors are represented 

with RGB values. For more information about RGB values, see the RGB 
structure in Chapter 6, “Data Types and Structures.” 


Table A.1 lists the raster-operation codes: 


Table A.1 


Raster-Operation Codes 


Boolean 
Function 
in Hex 


00 
01 
02 
03 
04 
05 
06 
07 
08 
09 
0A 
0B 
0C 
OD 
OE 
OF 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
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ROP 


00000042 
00010289 
00020C89 
000300AA. 
00040C88 
000500A9 
00060865 
000702C5 
00080F'08 
00090245 
000A0329 
OOOBOB2A 
000C0324 
00O0DO0B25 
OOOE08A5 
OOOF'0001 
00100C85 
001100A6 
00120868 
001302C8 
00140869 
001502C9 
001650CA 
00171D54 
00180D59 
00191CC8 


Boolean 


Function 


in Reverse Polish 


0 

DPSoon 
DPSona 
PSon 
SDPona 
DPon 
PDSxnon 
PDSaon 
SDPnaa 
PDSxon 
DPna 
PSDnaon 
SPna 
PDSnaon 
PDSonon 
Pn 

PDSona 
DSon 
SDPxnon 
SDPaon 
DPSxnon 
DPSaon 
PSDPSanaxx 
SSPxDSxaxn 
SPxPDxa 
SDPSanaxn 


Common 
Name 


BLACKNESS 


Table A.1 (continued) 


Boolean 
Function 
in Hex 


1A 
1B 
10 
1D 
1E 
IF 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
2A 
2B 
2C 
2D 
2 
2F 
30 
31 
32 
33 
34 
39 
36 
37 
38 
39 
3A 
3B 
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Hex 
ROP 


001A06C5 
001B0768 


001C06CA 


001D0766 
OO1EO1A5 
001F'0385 
00200F'09 
00210248 
00220326 
00230B24 
00240D55 
00251CC5 
002606C8 
00271868 
00280369 
002916CA 
002A0CC9 
002B1D58 
002C0784 
002D060A 
002E064A. 
002F0E2A 
0030032A 
00310B28 
00320688 
00330008 
00340604 
00351864 
003601A8 
00370388 
0038078A. 
00390604 
003A0644 
003BOE24 


Boolean 


Function 


in Reverse Polish 


PDSPaox 
SDPSxaxn 
PSDPaox 
DSPDxaxn 
PDSox 
PDSoan 
DPSnaa 
SDPxon 
DSna 
SPDnaon 
SPxDSxa 
PDSPanaxn 
SDPSaox 
SDPSxnox 
DPSxa 
PSDPSaoxxn 
DPSana 
SSPxPDxaxn 
SPDSoax 
PSDnox 
PSDPxox 
PSDnoan 
PSna 
SDPnaon 
SDPSoox 
on 
SPDSaox 
SPDSxnox 
SDPox 
SDPoan 
PSDPoax 
SPDnox 
SPDSxox 
SPDnoan 


Common 
Name 
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Table A.1 (continued) 


Boolean Boolean 
Function Hex Function Common 
in Hex ROP in Reverse Polish Name 
30 003C004A PSx - 
3D 003D18A4 SPDSonox - 
3E 0038E1B24 SPDSnaox - 
3F OO3FO0EA PSan - 
40 00400F 0A. PSDnaa - 
41 00410249 DPSxon - 
42 00420D5D SDxPDxa - 
43 00431CC4 SPDSanaxn - 
44 00440328 SDna SRCERASE 
45 00450B29 DPSnaon - 
46 004606C6 DSPDaox - 
47 0047076A. PSDPxaxn - 
48 00480368 SDPxa - 
49 004916C5 PDSPDaoxxn - 
4A 004A0789 DPSDoax - 
4B 004B0605 PDSnox - 
AC 004C0CC8 SDPana - 
4D 004D1954 SSPxDSxoxn - 
4E 004E0645 PDSPxox - 
4¥ 004F0E25 PDSnoan - 
50 00500325 PDna - 
51 00510B26 DSPnaon - 
52 005206C9 DPSDaox - 
53 00530764 SPDSxaxn - 
o4 005408A9 DPSonon - 
55 00550009 Dn DSTINVERT 
56 005601A9 DPSox - 
57 00570389 DPSoan - 
58 00580785 PDSPoax - 
59 00590609 DPSnox - 
5A 005A0049 DPx PATINVERT 
5B OO5B1i8A9 DPSDonox - 
5C 005C0649° DPSDxox - 
5D 005D0E29 DPSnoan - 
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Boolean 
Function 
in Hex 


5E 
5F 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
6A 
6B 
6C 
6D 
6E 
6F 
70 
71 
72 
73 
74 
75 
76 
V7 
78 
79 
TA 
7B 
7C 
7D 
7E 
7F 


Binary and Ternary Raster-Operation Codes and Definitions 


Hex 
ROP 


005E1B29 
0O5F00E9 
00600365 
006116C6 
00620786 
00630608 
00640788 
00650606 
00660046 
006718A8 
006858A6 
00690145 
006A01E9 
006B178A 
006CO01E8 
006D1785 
OO6E1E28 
OO6F'0C65 
00700CC5 
00711D5C 
00720648 
00730E28 
00740646 
00750E26 
00761B28 
007700E6 
007801E5 
00791786 
007A1E29 
007B0C68 
007C1E24 
007D0C69 
007E0955 
007F03C9 


Boolean 


Function 


in Reverse Polish 


DPSDnaox 
DPan 

PDSxa 
DSPDSaoxxn 
DSPDoax 
SDPnox 
SDPSoax 
DSPnox 

DSx 
SDPSonox 
DSPDSonoxxn 
PDSxxn 
DPSax 
PSDPSoaxxn 
SDPax 


~ PDSPDoaxxn 


SDPSnoax 
PDSxnan 
PDSana 
SSDxPDxaxn 


_SDPSxox 


SDPnoan 
DSPDxox 
DSPnoan 
SDPSnaox 
DSan 
PDSax 
DSPDSoaxxn 
DPSDnoax 
SDPxnan 
SPDSnoax 
DPSxnan 
SPxDSxo 
DPSaan 
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Table A.1 (continued) 


Boolean Boolean 

Function Hex Function Common 

in Hex ROP in Reverse Polish Name 
80 008003E9 DPSaa - 
81 00810975 SPxDSxon - 
82 00820C49 DPSxna - 
83 00831104 SPDSnoaxn - 
84 00840048 SDPxna . 
85 00851E05 PDSPnoaxn - 
86 008617A6 DSPDSoaxx - 
87 00870105 PDSaxn - 
88 OO8800CE6 DSa SRCAND 
89 00891B08 SDPSnaoxn - 
8A. OO8A0E06 DSPnoa - 
8B OO8BO0666 DSPDxoxn - 
8C 008COE08 SDPnoa - 
8D OO8D0668 SDPSxoxn - 
SE OOSEID7C SSDxPDxax - 
Sk OO8FOCE5  PDSanan - 
90 00900C45 PDSxna - 
91 0091108 SDPSnoaxn - 
92 009217A9 DPSDPoaxx - 
93 009301C4 SPDaxn - 
94 009417AA PSDPSoaxx - 
95 009501C9 DPSaxn : 
96 00960169 DPSxx - 
97 0097588A. PSDPSonoxx - 
98 00981888 SDPSonoxn - 
99 00990066 DSxn - 
9A. 009A0709 DPSnax - 
9B 009B07A8 SDPSoaxn - 
9C 00900704 SPDnax - 
9D 009D07A6 DSPDoaxn - 
9E OOSEI6E6 DSPDSaoxx - 
oF 0O09F' 0345 PDSxan - 
AO 00A000C9 DPa - 
Al 00A11B05 PDSPnaoxn - 
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| Boolean 
Function 
in Hex 


A2 
A3 
A4 


Binary and Ternary Raster-Operation Codes and Definitions 


Hex 
ROP 


00A20E09 
00A30669 
00A41885 
00A50065 
00A60706 
OOA707A5 
0OA803A9 
00A90189 
0O0AA0029 
OOABO889 
00AC0744 
OOADO6BES 
OOAEOBO6 
OOAF‘0229 
0OBO0E05 
0OB10665 
00B21974 
00B30CE8 
00B4070A 
00B507A9 
0OB616E9 
00B70348 
00B8074A. 
OOB906E6 
OOBAOBO9 
00BB0226 
OOBC1CE4 
0QOBDOD7D 
OOBE0269 
OOBF'08C9 
0OCOODO0CA. 
00C11B04 
00C21884 
00C3006A. 


Boolean 


Function 


in Reverse Polish 


DPSnoa 
DPSDxoxn 
PDSPonoxn 
PDxn 
DSPnax 
PDSPoaxn 
DPSoa 
DPSoxn 

D 

DPSono 
SPDSxax 
DPSDaoxn 
DSPnao 
DPno 
PDSnoa 
PDSPxoxn 
SSPxDSxox 
SDPanan 
PSDnax 
DPSDoaxn 
DPSDPaoxx 
SDPxan 
PSDPxax 
DSPDaoxn 
DPSnao 
DSno 
SPDSanax 
SDxPDxan 
DPSxo 
DPSano 
PSa 
SPDSnaoxn 
SPDSonoxn 
PSxn 


Common 
Name 


MERGEPAINT 


MERGECOPY 
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Table A.1 (continued) 


Boolean Boolean 

Function Hex Function Common 

in Hex ROP in Reverse Polish Name 
O4 00C40E04 SPDnoa - 
C5 00C50664 SPDSxoxn - 
C6 00C60708 SDPnax - 
C7 00C707AA PSDPoaxn - 
C8 00C803A8 SDPoa - 
C9 00C90184 SPDoxn - 
CA 00CA0749 DPSDxax - 
CB OOCBO6E4 SPDSaoxn - 
CC 00CC0020 S SRCCOPY 
CD 0OCD0888 SDPono - 
CE OOCEOB08 SDPnao - 
OF 0OCF 0224 SPno - 
DO OODOOE0A PSDnoa - 
D1 00D1066A § PSDPxoxn - 
D2 00D20705 PDSnax - 
D3 00D307A4 SPDSoaxn - 
D4 00D41D78 SSPxPDxax - 
D5 0OD50CE9 DPSanan - 
D6 OOD616EA PSDPSaoxx - 
D7 00D70349 DPSxan - 
D8 00D80745 PDSPxax - 
D9 OOD906E8 SDPSaoxn - 
DA OODAICE9 DPSDanax - 
DB OODBOD75 SPxDSxan - 
DC 0ODCOB04 SPDnao - 
DD 00DDG6228 SDno ~ 
DE OODE0268 SDPxo - 
DF OODFO8C8 SDPano - 
E0 0O0E003A5 PDSoa - 
El 00E10185 PDSoxn - 
2 00E20746 DSPDxax - 
E3 OOE306EA. PSDPaoxn - 
E4 00E40748 SDPSxax - 
E5 OOE506E5 PDSPaoxn - 
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Boolean 
Function 
in Hex 


Binary and Ternary Raster-Operation Codes and Definitions 


Hex 
ROP 


OOE61CE8 
00E70D79 
00E81D74 
OOE95CES6 
OOH A02E9 
OOEB0849 
OOEC02E8 
00ED0848 
OOLE0086 
OOEFOA08 
OOF'00021 
OOF 10885 
OOF 20B05 
OOF 3022A 
OOF 40B0A. 
00F50225 
OOF 60265 
OOF 708C5 
OOF 802E5 
00F 90845 
OOF A0089 
OOF BOA09 
OOF COO8A. 
OOF DOA0DA 
OOF E02A9 
OOF F'0062 


Boolean 


Function 


in Reverse Polish 


SDPSanax 
SPxPDxan 


SSPxDSxax 
DSPDSanaxxn 


DPSao 
DPSxno 
SDP ao 
SDPxno 
DSo 
SDPnoo 
P 
PDSono 
PDSnao 
PSno 
PSDnao 
PDno 
PDSxo 
PDSano 
PDSao 
PDSxno 
DPo 
DPSnoo 
PSo 
PSDnoo 
DPSoo 
1 


Common 
Name 


SRCPAINT 


PATCOPY 


WHITENESS 
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Appendix B> 


Binary-Resource File Format 
for Icons and Cursors 


This appendix describes the binary-resource file format for icons and cur- 
sors. [he Windows resource compiler creates the file from an application 
resource file (file with the .rc extension). The binary files contain a struc- 
ture that defines the type of object, specifies whether the object is device- 
independent, and gives the size of the object. Following this information 
are two bitmaps that serve as. bitmasks. The first bitmap 1s an AND mask; 
the second bitmap is an XOR mask. By combining the values in corre- 
sponding mask bits, Windows determines whether a pixel is black, white, 
inverted, or transparent. Figure B.1 shows what values are necessary to 
produce the corresponding colors, inversions, or transparencies: 


Resultant Pixel [Black {vise | Transparent inverted 


"Figure B: : Bit Mask Results 


mp 


Figure B.2 shows two 3 x 3 ea that represent the AND mask and 
the XOR mask for a cursor. ‘The: bit pean in the two bitmaps create a 
black, cross-shaped cursor: ~. ... ,. 


, gor Resultant 
Hank Mask - Cursor or Icon 


afeya| [elete 
a) eae ad 


Figure B.2 dittieaiand Resultant Cursor 
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The binary files that the Windows resource compiler creates have the 
following structure: 


BYTE bFigure; 

BYTE bIndependent; 
short xHotspot; 
short yHotspot; 
short cx; 

short cy; 

short WidthBytes; 
short clr; 


This information is followed by the bits of the AND mask, which are foi- 
lowed by the bits of the XOR mask. The fields are as follows: 


Field Description 
bF igure Specifies whether the structure is a cursor, a bit- 


map, or an icon. The value 1 indicates a cursor, 
2 indicates a bitmap, and 3 indicates an icon. 


bIndependent Specifies whether the object is device-dependent 
or device-independent. The value zero indicates 
device-dependent, and 1 indicates device- 


independent. 

xHotspot Specifies the z-coordinate of the cursor’s or icon’s 
hotspot. 

y Hotspot Specifies the y-coordinate of the cursor’s or icon’s 
hotspot. 

cx Specifies the z-extent of the cursor or icon. 

cy Specifies the y-extent of the cursor or icon. 

cbWidthBytes Specifies the bytes per row in the cursor or icon 
(note that the bytes must be aligned on a word 
boundary). 

clr Specifies the number of color planes (note that 


this value is always set to zero), 


Comments 
If the resource is a bitmap, a BITMAP data structure follows the 


bIndependent field. The xHotspot, yHotspot, cx, cy, cbWidthBytes, 
and elr fields are not part of the bitmap resource file. 
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Printer Escapes 


This appendix contains an alphabetical list of the individual Microsoft 
Windows printer escapes. The printer escapes allow applications to access 
facilities of a particular output device that are not available directly 
through GDI. The escape calls are made by an application, translated by 
Windows, and then sent to the device driver. 


short Escape(hDC, ABORTDOC, NULL, (LPSTR)NULL, 
LPSTR)NULL) 


This escape terminates the current job, erasing everything the application 
has written to the device since the last ENDDOC escape. 


The ABORTDOC escape should be used for printing operations that do 
not specify an abort function (that is, a SETABORTPROC escape), 
and to terminate printing operations that have not yet reached their first 


NEWFRAME or NEXTBAND escape call. 


Parameter Type/ Description 
hDC HDC Identifies the device context. 
Return Value 


The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 


Comments 
When a printing error occurs, the ENDDOC escape should not be used to 


terminate the printing operation, and the ABORTDOC escape should be 
used to terminate a next banding operation only. 


short Escape(hDC, BANDINFO, nCount, lpInData, lpOutData) 
This escape copies information about a device with banding capabilities to 


a structure pointed to by the lpInData parameter. Banding is a property of 
an output device that allows a page of output to be stored in a metafile 
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and divided into bands, each of which is sent to the device in order to 
create a complete page. Devices with banding capabilities avoid problems 
associated with devices that cannot scroll backward. 


The information copied to the structure pointed to by (pInData includes a 
value that indicates whether there are graphics in the next band, a value 
that indicates whether there is text on the page, and a rectangle structure 
that contains a bounding rectangle for all graphics on the page. 


Parameter Type/Description 

ADC HDC Identifies the device context. 

nCount- short Is not used; can be set to NULL. 

lpnInData LPSTR Points to a data structure that contains the 
following items: 
Field Type/ Description 
fGraphF lag BOOL Specifies whether there 


are graphics on the page. It is 
nonzero if there are graphics on 
the page. Otherwise, it is zero. 


fTextFlag BOOL Specifies whether there _ 
es See is text on the page. It is nonzero if | 
; there is text on the page. Other- 
a “ee “wise, 16 18 zero. 
rs ae RECT Contains a rectangle — 
eS ae structure with the coordinates for. 
-arectangle that bounds the page. 


lnOutData_ - -LPSTR. Points toa data ‘structure that contains the 
~ following items: 


Field > Type/Description 


fGraphF lag. BOOL Specifies whether there 
_ are graphics on the page. It is 

nonzero if there are graphics on 
the page. Otherwise, it is zero. 


fTextFlag BOOL Specifies whether there 
is text on the page. It is nonzero if 
there is text on the page. Other- 
wise, it 1s zero. 


GraphicsRect RECT Contains a rectangle 
structure with the coordinates 
for a rectangle that bounds the 
current band. 
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Return Value 


The return value specifies the outcome of the escape. It is 1 if the escape is 
successful. Otherwise, it is zero. 


Comments 
The [pOutData parameter should be NULL if no data are returned. This 


escape should be implemented only for devices that use banding. It should 
be called immediately after each cali to the NEX‘TBAND escape. 


short Escape(hDC, DEVICEDATA, nCount, lpInData, IpOutData) 


This escape allows the application to send data directly to the printer, 
bypassing the standard print-driver code. 


Parameter Type/ Description 

hDC HDC Identifies the device context. 

nCount . short Specifies the number of bytes of device data 
to be passed to the printer. © 

loInData LPSTR Points to a structure whose first word 


16 bits) contains the number of bytes of input data. 
The remaining bytes of the structure contain the data 
itself. 


ipOutData = LPSTR Is not used; can be set to NULL. 


Return Value 


The return value specifies the number of bytes transferred to the printer if 
the escape is successful. It is zero if the escape is not successful or is not 
implemented. If the return value is nonzero but less than that specified in 
the nCount parameter, an error has prohibited transmission of the entire 


data block. 

Comments 

There may be restrictions on the kinds of device data an application may 
send to the device without interfering with the operation of the driver. In 
general, applications must avoid resetting the printer or causing the page 
to be printed. 


It is strongly recommended that applications not perform functions that 
consume printer memory, such as downloading a font or a macro. 
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The driver should invalidate its internal-state variables, such as 
CURRENT- POSITION and CURRENT_ LINE_ STYLE, when execut- 
ing this escape. The driver may issue a printer save command prior to 
transmitting the first of a sequence of DEVICEDATA escapes, and 
issue a restore command prior to executing the first command following 
the last DEVICEDATA escape. In other words, the application must 
be able to issue multiple, sequential DEVICEDATA escapes without 
intervening save and restore commands inserted by the driver. 


short Escape(hDC, DRAFTMODE, 2, IpDraftMode, (LPSTR)NULL) 


This escape turns draft mode off or on. Turning draft mode on instructs 
the device driver to print faster and with lower quality (if necessary). The 
draft mode can be changed only at page boundaries, for example, after a 


NEWFRAME escape. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


lpDraftMode LPINT Points to a short-integer value that specifies 
the draft mode; 1 specifies draft mode on, zero spec- 
ifies draft mode off. 


Return Value 


The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 


Comments 


The default draft mode is off. 


short Escape(hDC, DRAWPATTERNRECT, nCount, lpInData, 
lp OutData) 


This escape creates a pattern, gray scale, or solid black rectangle by using 
the pattern /rule capabilities of PCL (HP LaserJet or LaserJet-compatible) 
printers. A gray scale is a gray pattern that contains a specific mixture of 

black and white pixels. 
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Parameter Type/Description 


hDC HDC Identifies the device context. 
nCount short Is not used; can be set to NULL. 
lnInData LPSTR Points to a data structure that contains the 


following fields: 
Field Type/Description 


prPosition POINT Specifies the upper-left 
corner of the rectangle. 


prSize POINT Specifies the lower-right 
corner of the rectangle. 

prstyle WORD Specifies the type of pat- 
tern. It can be one of the following 
values: 
0 Black rule 
2 Gray scale 
3 HP-defined 


prPattern WORD Specifies the pattern. 
It is ignored for a black rule. It 
specifies the percent of gray for a 
gray-scale pattern. It represents 
one of six HP-defined patterns. 


lpOutData LPSTR Is not used; can be set to NULL. 


Return Value 


The return value specifies the outcome of the escape. It is 1 if the escape is 
successful. Otherwise, it is zero. 


Comments 


An application should use the QUERYESCSUPPORT escape to 
determine whether a device is capable of drawing patterns and rules 
before implementing the DRAWPATTERNRECT escape. If an appli- 
cation uses the BANDINFO escape, all patterns and rectangles sent 

by using DRAWPATTERNRECT should be treated as text and sent 


on a text band. 
Patterns and rules created with the DRAWPATTERNRECT escape 


may not be erased by placing opaque objects over them. An application 
should use the function calls provided in GDI to obtain this effect. 
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short Escape(hDC, ENABLEDUPLEX, nCount, IpInData, lpOutData) 


This escape enables the duplex printing capabilities of a printer. A device 
that possesses duplex printing capabilities is able to print on both sides of 
the output medium. 


Parameter Type/ Description 
hDC HDC Identifies the device context. 
nCount short Specifies whether duplex or simplex printing 


is used. A nonzero value indicates that duplex printing 
should be enabled; zero indicates that simplex print- 
ing should be enabled. 


lpInData LPSTR Is not used; can be set to NULL. 
lp OutData LPSTR Is not used; can be set to NULL. 


Return Value 


The return value specifies the outcome of the escape. It is 1 if the escape 1s 
successful. Otherwise, it 1s zero. 


Comments 


An application should use the QUERYESCSUPPORT escape to deter- 
mine whether an output device is capable of creating duplex output. If 
QUERYESCSUPPORT returns a nonzero value, the application should 
send the ENABLEDUPLEX escape even if simplex printing is desired. 
This guarantees replacement of any values set in the driver-specific } 

— dialog box. If duplex printing is enabled and an uneven number of 
NEXTFRAME escapes are sent to the driver prior to the ENDDOC 
escape, the driver will add one page eject before ending the print job: 


short Escape(hDC, ENABLEPAIRKERNING, nCount, lpInData, 
lpOutData) 


This escape enables or disables the driver’s ability to kern character 
pairs automatically. Kerning is the process of adding or subtracting 
space between characters in a string of text. When enabled, the driver 
automatically kerns those pairs of characters that are listed in the 
font’s character-pair kerning table. The driver reflects this kerning 
both on the printer and in Get TextExtent function calls. 
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Parameter Type/Description 


hDC HDC Identifies the device context. 

nCount short Specifies the number of bytes used by the 
loInData parameter. This value should be set to 2. 

lpInData LPSTR Points to a short-integer value that specifies 


whether automatic pair kerning is to be enabled (1) or 


disabled (0). 


lpOutData LPSTR. Points to a short-integer value that will 
receive the previous automatic pair-kerning value. 


Return Value 


The return value specifies the outcome of the escape. It is 1 if the escape 
is successful; it is zero if the escape is not successful. If the escape is not 
implemented, the return value is zero. 


Comments 


The default state of this escape is zero; automatic character-pair kerning 
is disabled. 


A driver does not have to support the ENABLEPAIRKERNING escape 
just because it supplies the character-pair kerning table to the application 
via the GETPAIRKERNTABLE escape. In the case where the GET- 
PAIRKERNTABLE escape is supported but the ENABLEPAIR- 
KERNING escape is not, the application must properly space the 

kerned characters on the output device. 


short Escape(hDC, ENABLERELATIVEWIDTHS, nCount, 
lpInData, IpOutData) 


This escape enables or disables relative character widths. When disabled 
the default), each character’s width can be expressed as a number of 
evice units. This guarantees that the extent of a string will equal the 

sum of the extents of the characters in the string. This allows applications 

to build an extent table by using one-character Get TextExtent function 
calls. When enabled, the sum of a string may not equal the sum of the 
widths of the characters. Applications that enable this feature are 
expected to retrieve the font’s extent table and compute relatively 

scaled string widths. , 
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Parameter Type/Description 

hDC HDC Identifies the device context. 

nCount short Specifies the number of bytes used by the 
lpInData parameter. This value should be set to 2. 

loInData LPSTR Points to a short-integer value that spec- 


ifies whether relative widths are to be enabled (1) or 
disabled (0). 


lpOutData LPSTR. Points to a short-integer value that will 
receive the previous relative character width value. 


Return Value 
The return value specifies the outcome of the escape. It is 1 if the escape 


is successful; it is zero if the escape is not successful. If the escape is not 
implemented, the return value is zero. 


Comments 


The default state of this escape is zero; relative character widths are dis- 


abled. 
The values specified as font units and that are accepted and returned by 
the escapes described in this appendix are returned in the relative units of 


the font when the ENABLERELATIVEWIDTUHS escape is enabled. 


It is assumed that only linear-scaling devices will be dealt with in a rela- 
tive mode. Nonlinear-scaling devices should not implement this escape. 


short Escape(hDC, ENDDOC, NULL, (LPSTR)NULL, 
(LPSTR)NULL) 


This escape ends a print job started by a STARTDOC escape. 
Parameter Type/Description 


hDC HDC Identifies the device context. 
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Return Value 


The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 


When a printing error occurs, the ENDDOC escape should not be used 
to terminate the printing operation, and the ABORTDOC escape should 
only be used to terminate a next banding operation. 


short Escape(hDC, EXTTEXTOUT, nCount, lpInData, lpOutData) 


This escape provides an efficient way for the application to call the GDI 
TextOut function when justification, letterspacing, and/or kerning is 
involved. | 


Parameter Type/Description 

hDC HDC Identifies the device context. 

nCount short Specifies the number of bytes used by the 
lnInData parameter. 

loInData LPSTR Points to a data structure that contains 

the following fields: 

Field Type/Description 

xX WORD Specifies the z-coordinate of 
the upper-left corner of the string’s start- 
ing point. 

Y WORD Specifies the y coordinate of 
the upper-left corner of the string’s start- 
ing point. 

lp Text WORD Points to an array of cch char- 


acter codes. The cch parameter is the 
number of bytes in the string (cch is also 
the number of words in the width array). 
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lp Widths WORDFAR * Points to an array 
of ech character widths to use when 
printing the string. The first character 
appears at (X,Y), the second at 
X + IpWidths/0],Y), the third at 
X + IpWidths/0} + Ubi ,Y), 
and so on. These character widths are 
specified in the font units of the currently 
selected font. (The character widths will 
always be equal to device units unless the 
application has enabled relative character 
widths. ) 


The units contained in the width array 
are specified as font units of the device. 


lpOutData LPSTR Is not used; can be set to NULL. 


Return Value 
The return value specifies the outcome of the escape. It is 1 if the escape 


is successful; it is zero if the escape is not successful. If the escape is not 
implemented, the return value is zero. 


short Escape(hDC, FLUSHOUTPUT, NULL, (LPSTR)NULL, 
LPSTR)NULL) : 


This escape flushes output in the device’s buffer. 
Parameter Type/ Description 

hDC HDC Identifies the device context. 
Return Value 


The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 
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short Escape(hDC, GETCOLORTABLE, NULL, IpIndez, lp Color) 


This escape retrieves an RGB color-table entry and copies it to the loca- 
tion specified by the /pColor parameter. 


Parameter Type/ Description 
hDC HDC Identifies the device context. 
lpIndex LPSTR Points to a short-integer value that specifies 


the index of a color-table entry. Color-table indexes 
start at zero for the first table entry. 


lpColor LPSTR Points to the long-integer value that will 
receive the RGB color value for the given entry. 


Return Value 


The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, 1t 1s negative. 


short Escape(hDC, GETEXTENDEDTEXTMETRICS, nCount, 
| lpInData, lpOutData) 


This escape fills the buffer pointed to by the IpOutData parameter with the 
extended text metrics for the selected font. 


Parameter Type/Description 


hDC HDC Identifies the device context. 
nCount short Is not used; can be set to NULL. | 
loInData LPSTR Points to a data structure that contains the 
following field: 
Field Type/ Description 
nSize WORD Specifies the number of 
bytes pointed to by the lpOutData 
parameter, 
lnOutData LPSTR Points to an EXTTEXTMETRIC data 
structure. — 
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Return Value 


The return value specifies the number of bytes copied to the buffer pointed 
to by the lpOutData parameter. This value will never exceed that speci- 
fied in the nSize parameter and will be zero if the escape fails or 1s not 
implemented. 


Comments 


The values returned in many of the fields of the EX TTEXTMETRIC 
structure are affected by whether relative character widths are enabled or 
disabled. For more information, see the ENABLERELATIVEWIDTHS 


escape, earlier in this appendix. 


short Escape(hDC, GETEXTENTTABLE, nCount, IpInData, 
lpOutData) 


This escape returns the width (extent) of individual characters from a 
group of consecutive characters in the selected font’s character set. The 
first and last characters (from the group of consecutive characters) are 
function arguments. 


Parameter Type/Description 


hDC HDC Identifies the device context. 

nCount short Is not used; can be set to NULL. 

lpInData LPSTR Points to a data structure that contains the 
following fields: 
Field Type/Description 
chFirst BYTE Specifies the character 


code of the first character. 


chLast BYTE Specifies the character 
code of the last character. 


lnOutData LPSTR Points to an array of short type. The size of 
the array must be at least (chLast — chFirst + 1). 
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Return Value 


The return value specifies the outcome of the escape. It is 1 if the escape 
is successful; it is zero if the escape is not successful. If the escape is not 
implemented, the return value is zero. 


Comments 


The values returned are affected by whether relative character 
widths are enabled or disabled. For more information, see the 


ENABLERELATIVEWIDTHS escape, earlier in this appendix. 


short Escape(hDC, GETPAIRKERNTABLE, nCount, IpInData, 
lpOutData) 


This escape fills the buffer pointed to by the lpOutData parameter with the 
character-pair kerning table for the selected font. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

nCount short Is not used; can be set to NULL. 
lpnInData LPSTR Is not used; can be set to NULL. 
lpOutData LPSTR Points to an array of KERNPAIR 


structures. This array must be large enough to 
accommodate the font’s entire character-pair 
kerning table. The number of character-kerning 
pairs in the font can be obtained from the 
EXTTEXTMETRIC structure returned by the 
GETEXTENDEDTEXTMETRICS escape. 


Return Value 


The return value specifies the number of KERNPAIR structures copied 
to the buffer. This value is zero if the font does not have kerning pairs 
defined, or the escape fails or is not implemented. | 


Comments 


The values returned in the KERNPAIR structures are affected by 
whether relative character widths are enabled or disabled. For more 
information, see the ENABLERELATIVEWIDTHS escape, earlier 
in this appendix. 
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short Escape(hDC, GETPHYSPAGESIZE, NULL, (LPSTR)NULL, 


lpDimensions) 


This escape retrieves the physical page size and copies it to the location 
pointed to by the /pDimensions parameter. 


Parameter Type/ Description 


ADC HDC Identifies the device context. 
lp Dimensions LPSTR Points to the POINT data structure that 
will receive the physical page dimensions. 


Return Value 


The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 


short Escape(hDC, GETPRINTINGOFFSET, NULL, (LPSTR)NULL, 
lp Offset) 


This escape retrieves the offset from the upper-left corner of the physical 
page, where the actual printing or drawing begins. This escape is generally 
not useful for devices that allow the user to set the printable origin by 
hand. 


Parameter Type/Description 


ADC HDC | Identifies the device context. 


lnOffset LPSTR Points to the POINT structure that will 
receive the printing offset. 


Return Value 


The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 
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short Escape(hDC, GETSCALINGFACTOR, NULL, (LPSTR)NULL, 
lpFactors) 


This escape retrieves the scaling factors for the x» and yaxes of a printing 
device. For each scaling factor, the escape copies an exponent of 2 to the 
location pointed to by the [pFactors parameter. For example, the value 3 is 
copied to lpFactors if the scaling factor is 8. 


Scaling factors are used by printing devices that cannot support graphics 
at the same resolution as the device resolution. 


Parameter Type/Description 
hDC HDC | Identifies the device context. 
lpFactors LPSTR Points to the POINT data structure that 


will receive the scaling factor. 


Return Value 


The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 


short Escape(hDC, GETTRACKKERNTABLE, nCount, IpInData, 
lp OutData) 


This escape fills the buffer pointed to by the IpOutData parameter with the 
track kerning table for the currently selected font. 


Parameter Type/ Description 

hDC HDC Identifies the device context. 

nCount short Is not used; can be set to NULL. 

loInData LPSTR Is not used; can be set to NULL. 
lpOutdata LPSTR Points to an array of KERNTRACK 


structures. This array must be large enough to 
accommodate all the font’s kerning tracks. The 
number of tracks in the font can be obtained from 
the EXTTEXTMETRIC structure returned 

by the GETEXTENDEDTEXTMETRICS 


escape. 
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Return Value 


The return value specifies the number of KERNTRACK structures 
copied to the buffer. This value is zero if the font does not have kerning 
tracks defined, or the escape fails or is not implemented. 


Comments 


The values returned in the KERNTRACK structures are affected by 
whether relative character widths are enabled or disabled. For more infor- 
mation, see the ENABLERELATIVEWIDTHS escape, earlier in this 
appendix. 


BOOL Escape(hDC, MFCOMMENT, nCount, lpComment, 


(LPSTR)NULL) 
This escape adds a comment to a metafile. 
Parameter Type/Description 
hDC HDC Identifies the device context for the device on 


which the metafile appears. 


nCount short Specifies the number of characters in the string 
pointed to by the lpComment parameter. 


lpComment LPSTR Points to a null-terminated string that con- 
| tains the comment that will appear in the metafile. 


Return Value 
The return value specifies the outcome of the escape. It is —1 if an error 


such as insufficient memory or an invalid port specification occurs. Other- 
wise, it is positive. 


short Escape(hDC, NEWFRAME, NULL, aia cia 
LPSTR)NULL) 


This escape informs the device that the application has finished writing 
to a page. This escape is typically used with a printer to direct the device 
driver to advance to a new page. 


Parameter Type/ Description 


hDC HDC | Identifies the device context. 
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Return Value 


The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is one of the following values: 


SP_ APPABORT Job was terminated because the application’s 
abort function returned zero. 

SP.. ERROR General error. 

SP_ OUTOFDISK Not enough disk space is currently available 
for spooling, and no more space will become 
available. 


SP_OUTOFMEMORY Not enough memory is available for spooling. 


SP_ USERABORT User terminated the job through the spooler 
task. 


short Escape(hDC, NEXTBAND, NULL, (LPSTR)NULL, [pBandRect) 


This escape informs the device driver that the application has finished 
writing to a band, causing the device driver to send the band to the 
spooler and return the coordinates of the next band. This escape is used 
by applications that process banding themselves. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


lnBandRect LPSTR Points to the RECT data structure that will 
receive the next band coordinates. The device driver 
copies the device coordinates of the next band into this 
structure. 


Return Value 


The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is one of the following values: 


SP_ APPABORT Job was terminated because the application’s 
abort function returned zero. 

SP_ ERROR General error. 

SP_ OUTOFDISK Not enough disk space is currently available 
for spooling, and no more space will become 
available. 
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SP. OUTOFMEMORY Not enough memory is available for spooling. 
SP_ USERABORT User terminated the job through the spooler 


task. 


short Escape(hADC, QUERYESCSUPPORT, 2, (pHscNum, 
(LPSTR)NULL) 


This escape finds out whether a particular escape is implemented by the 
device driver. 


Parameter Type/ Description 
hDC HDC Identifies the device context. 
loEscNum LPSTR Points to a short-integer value that specifies 


the escape function to be checked. 
Return Value 


The return value specifies whether a particular escape is implemented. It 
is nonzero for implemented escape functions. Otherwise, it is zero. 


short Escape(hDC, SETABORTPROC, NULL, [pAboriF unc, 
LPSTR)NULL) 


This escape sets the abort function for the print job. If an application 
wants to allow the print Job to be canceled during spooling, 1t must set 
the abort function before the print job is started with the STARTDOC 
escape. The spooler calls the abort function during spooling to allow the 
application to cancel the print job or to process out-of-disk-space condi- 
tions. If no abort function is set, the print job will fail if there is not 
enough disk space for spooling. 


Parameter Type/ Description 


hDC HDC Identifies the device context. 


lnAbortfunc FARPROC Points to the application-supplied abort 
function. See the following “Comments” section for 
details. 
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Return Value 


The return value specifies the outcome of the escape. It is positive if the 
escape 1s successful. Otherwise, it is negative. 


Comments 


The address passed as the lpAbortF'unc parameter must be created by 
using the MakeProcInstance function. 


The callback function must use the Pascal calling convention and must be 
declared FAR. The abort function must have the following form: 


short FAR PASCAL AbortFunc(hPr, code) 

HDC hPr; 

short code; 

AbortFunc is a placeholder for the application-supplied function name. 


The actual name must be exported by including it in an EXPORTS 
statement in the application’s module-definition file. 


Parameter Description 
hPr Identifies the device context. 
code Specifies whether an error has occurred. It is zero if no 


error has occurred. It is SP_ OUTOFDISK if the spooler 
is currently out of disk space and more disk space will 
become available if the application waits. 


Return Value 


The return value should be nonzero if the print job is to continue, and 
zero if it is canceled. 


short Escape(hDC, SETALLJUSTVALUES, nCount, IpInData, 
Ip OutData) 


This escape sets all of the text-justification values that are used for text 
output. Text justification is the process of inserting extra pixels among 
break characters in a line of text. The blank character is normally used 
as a break character. 
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Parameter Type/ Description 

hDC HDC Identifies the device context. 

nCount short Is not used; can be set to NULL. 

lpInData LPSTR Points to a data structure that contains the 


following items: 
Field Type/Description 


nCharExtra short Specifies the total extra 
space (in font units) that must be 
distributed over nCharCount 
characters. 


nCharCount WORD Specifies the number 
of characters over which 
nCharExtra is distributed. 


nBreakExtra short Specifies the total extra 
space (in font units) that is 
distributed over nBreakCount 
characters. 


nBreakCount WORD Specifies the number 
of break characters over which 
nBreakExtra is distributed. 


lp OutData LPSTR Is not used and can be set to NULL. 


Return Value 


The return value specifies the outcome of the escape. It is 1 if the escape 
is successful. Otherwise, it 1s zero. 


Comments 


The units used for nCharExtra and nBreakExtra are the font units 
of the device and are dependent on whether relative character widths 
were enabled with the ENABLERELATIVEWIDTHS escape. 


The values set with this escape apply to subsequent calls to the TextOut 
function. The driver stops distributing the extra space specified in the 
nCharExtra field when it has output nCharCount characters. Likewise, 
it stops distributing the space specified by the nBreakExtra field when 

it has output nBreakCount characters. A call on the same string to 

the Get TextExtent function made immediately after the call to the 
TextOut function will be processed in the same manner. 
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In order to reenable justification with the Set TextJustification and 
Set TextCharacterExtra functions, an application should call the 
SETALLJUSTVALUES escape and set the nCharExtra and 
nBreakExtra fields to zero. 


short Escape(hDC, SETCOLORTABLE, NULL, [pColorEntry, lpColor) 


This escape sets an RGB color-table entry. If the device cannot supply the 
exact color, the function sets the entry to the closest possible approxima- 
tion of the color. 


Parameter Type/Description 


ADC HDC Identifies the device context. 


lpColorEntry LPSTR = Identifies a color-table entry data structure. 
| The structure has the following fields: 


Field Type/Description 
Index WORD Specifies the color-table index. 
Color-table entries start at zero for the 
first entry. 
rgb LONG Specifies the desired RGB color 
value. 
lpColor LPSTR Points to the long-integer value that is 


to receive the RGB color value selected by the 
device driver to represent the requested color value. 


Return Value 


The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 


Comments 


A device’s color table is a shared resource; changing the system display 
color for one window changes it for all windows. 


The SETCOLORTABLE escape has no effect on devices with fixed 
color tables. 
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short Escape(hDC, SETCOPYCOUNT, nCount, IpInData, lp OutData) 


This escape specifies the number of uncollated copies of each page that the 
printer is to print. 


Parameter Type/ Description 

hDC HDC Identifies the device context. 

nCount short Specifies the number of bytes used by the 
loInData parameter. This value should be set to 2. 

loInData LPSTR Points to a short-integer value that contains 
the number of uncollated copies to be printed. 

lpOutData LPSTR Points to a short-integer value that will 


receive the number of copies to be printed. This may be 
less than the number requested if the requested number 
is greater than the device’s maximum copy count. 


Return Value 


The return value specifies the outcome of the escape. It is 1 if the escape 
is successful; it is zero if the escape is not successful. If the escape is not 
implemented, the return value is zero. 


short Escape(hDC, SETKERNTRACK, nCount, IpInData, IpOutData) 


For drivers that support automatic track kerning, this escape specifies 
which kerning track will be used. A kerning track of zero disables auto- 
matic track kerning. When enabled, the driver will automatically kern all 
characters according to the specified track. The driver will reflect this 
kerning both on the printer and in Get TextExtent function calls. 


Parameter Type/Description 


hDC HDC Identifies the device context. 

nCount short Specifies the number of bytes used by the 
loInData parameter. This value should be set to 2. 

loInData LPSTR Points to a short-integer value that specifies 


the kerning track to use. A value of zero disables this 
feature. Values in the range | to nKernTracks 
correspond to positions in the track-kerning table (using 
1 as the first item in the table). For more information, 
see the EX TTEXTMETRIC structure in Chapter 6, 
“Data Types and Structures.” 
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lp OutData LPSTR © Points to a short-integer value that will 
receive the previous kerning track. 


Return Value 


The return value specifies the outcome of the escape. It is 1 if the escape 
is successful; it is zero if the escape is not successful. If the escape is not 
implemented, the return value is zero. 


Comments 
Automatic track kerning is disabled by default. 


A driver does not have to support the ENABLEPAIRKERNING escape 
just because it supplies the track-kerning table to the application by using 
the GETTRACKKERNTABLE escape. In the case where GHT- 
TRACKKERNTABLE is supported but the SETKERNTRACK 
escape is not, the application must properly space the characters on the 
output device. : 


short Escape(hDC, SETLINECAP, nCount, IpInData, lpOutData) 


This escape sets the line end cap. An end cap is that portion of a line seg- 
ment that appears on either end of the segment. The cap may-be-square- -- 
or circular, it can extend past, or remain flush with, the specified segment 
end points. | 


Parameter Type/Description 

hDC HDC Identifies the device context. 

nCount int Is not used; can be set to NULL. 

loInData LPSTR Points to a short-integer value that specifies 


the end-cap type. The possible values and their mean- 
ings are given in the following list: 


Value Meaning 
~] Line segments are drawn by using the 
default GDI end cap. 
0 Line segments are drawn with a squared 


end point that does not project past the 
specified segment length. 
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1 Line segments are drawn with a rounded 
end point; the diameter of this semicircu- 
lar are is equal to the line width. 


2 Line segments are drawn with a squared 
end point that projects past the specified 
segment length. The projection is equal 
to half the line width. 


lpOutData LPSTR. Points to a short-integer value that specifies 
the previous end-cap setting. 


Return Value 


The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 


Comments 


The interpretation of this escape varies with page-description languages 
(PDLs). Consult your PDL documentation for its exact meaning. 


short Escape(hDC, SETLINEJOIN, nCount, IpInData, lpOutData) 


This escape specifies how a device driver will join two intersecting line seg- 
ments. The intersection can form a rounded, squared, or mitered corner. 


Parameter Type/ Description 

hDC | HDC Identifies the device context. 

nCount int Is not used; can be set to NULL. 

loInData LPSTR Points to a short-integer value that specifies 


the type of intersection. The possible values and their 
meanings are given in the following list: 


Value Meaning 
—I Line segments are joined by using the 
default GDI setting. 
0 Line segments are joined with a mitered 


corner; the outer edges of the lines extend 
until they meet at an angle. This is 
referred to as a miter join. 
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1 Line segments are Joined with a rounded 
corner; a semicircular are with a diameter 
equal to the line width is drawn around 
the point where the lines meet. This is 
referred to as a round join. 


2 Line segments are joined with a squared 
end point; the outer edges of the lines are 
not extended. This is referred to as a 
bevel join. 


lnOutData LPSTR Points to a short-integer.value that specifies 
the previous line join setting. 


Return Value 


The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 


Comments 


The interpretation of this escape varies with page-description languages 
(PDLs). Consult your PDL documentation for its exact meaning. 


If an application specifies a miter join but the angle of intersection is too 


small, the device driver ignores the miter setting and uses a bevel join 
instead. 


short Escape(hDC, SETMITERLIMIT, nCount, lpInData, IpOutData) 


This escape sets the miter limit for a device. The miter limit controls the 
angle at which a device driver replaces a miter join with a bevel join. 


Parameter Type/ Description 

hDC HDC Identifies the device context. 

nCount int Is not used; can be set to NULL. 

loInData LPSTR Points to a short-integer value that specifies 


the desired miter limit. Only values greater than or 
equal to -1 are valid. If this value is —1, the driver will 
use the default GDI miter limit. 


inOutData LPSTR Points to a short-integer value that specifies 
the previous miter-limit setting. 
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Return Value 


The return value specifies the outcome of the escape. It is positive if the 
escape is successful. Otherwise, it is negative. 


Comments 

The miter limit is defined as follows: 
miter length/line width = 1/sin(X/2) 

X is the angle of the line join in radians. 


The interpretation of this escape varies with page-description languages 
(PDLs). Consult your PDL documentation for its exact meaning. 


short Escape(hDC, STARTDOC, nCount, IpDocName, (LPSTR)NULL) 


This escape informs the device driver that a new print job is starting and 
that all subsequent NEWFRAME calls should be spooled under the same 
job until an ENDDOC call occurs. This ensures that documents longer 
than one page will not be interspersed with other jobs. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

nCount short Specifies the number of characters in the string 
pointed to by the IpDocName parameter. 

lpDocName LPSTR Points to a null-terminated string that spec- 


ifies the name of the document. The document name is 
displayed in the spooler window. 


Return Value 
The return value specifies the outcome of the escape. It is —1 if an error 


such as insufficient memory or an invalid port specification occurs. Other- 
wise, 1t 1s positive. 
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Comments 


The correct sequence of events in a printing operation are as follows: 
1. Create the device context. 


2. Set the abort function to keep out-of-disk-space errors from ter- 
minating a printing operation. 


An abort procedure that handles these errors must be set by using 


the SETABORTPROC escape. 
3. Begin the printing operation with the STARTDOC escape. 


Begin each new page with the NEWFRAME escape, or each new 
band with the NEXTBAND escape. 


5. End the printing operation with the ENDDOC escape. 
Note that when a printing error occurs, the ENDDOC escape should 


not be used to terminate the printing operation, and the ABORTDOC 
escape should only be used to terminate a next banding operation. 


short Escape(hDC, STRETCHBLT, nCount, IpInData, Ip OutData) 


This escape implements the GDI StretchBlt function on the driver level. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

nCount short Specifies the number of bytes used by the 
loInData parameter. 

lnInData LPSTR Points to a data structure. See the following 
“Comments” section for details. 

lp OutData LPSTR Is not used; can be set to NULL. 


Return Value 
The return value specifies the outcome of the escape. It is 1 if the escape 


is successful; it is zero if the escape is not successful. If the escape is not 
implemented, the return value is zero. 
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Comments 


The data structure pointed to by the IpInData parameter contains the fol- 
lowing items: 


WORD X, Y; 

WORD nWidth, nHeight; 
WORD XSrc, YSre; 
WORD nSrcWidth; 
WORD nSrcHeight; 
DWORD dwRop; 

short bmType; 

short bmWidth; 
short bmHeight: 
short bmWidthBytes; 
short bmPlanes; 
short bmBitsPixel; 
LPSTR bmBits: 


The bmBits field of this BITMAP structure is a long pointer to 

the bitmap bits. This pointer must be set by the application. The 
STRETCHBLT escape should be implemented only for devices with 
bitmap-stretching capabilities. For more information, see the BITMAP 
structure in Chapter 6, “Data Types and Structures.” 


The driver need not implement all of the GDI raster operations, but must 


return zero if the specific raster operation (ROP) cannot be implemented. 
The driver must not substitute one ROP for another. 
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Index 


ABORTDOC, 681 

ABSOLUTE, 440 

Accelerators, 24, 68 

AccessResource, 148 

AddAtom, 148 

AddFontResource, 149 

Adjust WindowRect, 150 

AllocResource, 150 

ALLTHRESHOLD, 496 

ALTERNATE, 294, 436 

ANSI character set, 121 

ANSL FIXED_ FONT, 302 

ANSI_ VAR_ FONT, 302 

AnsiLower, 151 

AnsiNext, 151 

AnsiPrev, 152 

AnsiToOem, 152 

AnsiUpper, 153 

AnyPopup, 153 

API (Application Programming 
Interface), 3 

API library, 3-4 

Application programming interface 

Arc, 154 

ASPECTX, 271 

ASPECTXY, 271 

ASPECTY, 271 

Atom, 139 

Atom-manager functions, 139-140 


Background brush, class, 30 
Background color, 52, 99 
Background mode, 52, 99 
BANDINFO, 681 
Banding, 132-133 
BaudRate, 614 
BeginPaint, 156 

BitBlt, 156 

BITMAP, 609 

Bitmap functions, 111-112 
BITSPIXEL, 270 
BLACK~ BRUSH, 302 
BLACK~ PEN, 302 
BLACKNESS, 159 
BLACKONWHITE, 447 
BM_ GETCHECK, 519 
BM_ GETSTATE, 519 
BM. SETCHECK, 520 


BM_SETSTATE, 520 
BM_SETSTYLE, 520 
bmBits, 609 
bmBitsPixel, 609 
bmHeight, 609 
bmPlanes, 609 
bmType, 609 
bmWidth, 609 
bmWidthBytes, 609 
BN_ CLICKED, 511, 522 
BN_ DISABLE, 511, 523 
BN _ DOUBLECLICKED, 523 
BN... HILITE, 511, 524 
BN_ PAINT, 511, 524 
BN UNHILITE, 511, 525 
Bold type, 12, 118 
BOOL type, 607 
bottom, 630 
Bounding rectangle, 111 
Brackets, double, 12 
BringWindowToTop, 159 
Brush origin, default, 52 
Brush 
alignment, 58-59 
class background, 30 
default, 52 
predefined, 95 
BS... 3STATE, 202, 522 
BS. AUTO8STATE, 201, 521 
BS_ AUTOCHECKBOX, 201, 521 
BS. AUTORADIOBUTTON, 521 
BS_ CHECKBOX, 201, 521 
BS_ DEFPUSHBUTTON, 521 
BS_ GROUPBOX, 201, 521 
BS_ HATCHED, 619 
BS. HOLLOW, 619 
BS_ INDEXED, 619 
BS_ LEFTTEXT, 201, 521 
BS.. PATTERN, 619 
BS... PUSHBUTTON, 521 
BS_ RADIOBUTTON, 522 
BS_ SOLID, 619 
BS_. USERBUTTON, 522 
BuildCommDCB, 160 
BUTTON, 198, 201, 202 
Button control, 71-72 
Button-control messages, 508 
Button notification codes, 511 
BYTE type, 607 
ByteSize, 614 
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Cache, display context, 55 
Calling convention, Windows, 10 
CallMsgF ilter, 161 
CallWindowProc, 161 
Caret, 80-82 
Caret functions, 80 
Catch, 162 
cbClsExtra, 635 
cbInQue, 612 
cbOutQue, 612 
cbWndExtra, 635 
cBytes, 628 
CE. BREAK, 265 
CE_ CTSTO, 265 
CE DNS, 265 
CE. DSRTO, 265 
CE... FRAME, 265 
CE_ IOE, 265 
CE_ MODE, 265 
CE_ OOP, 265 
CE.. OVERRUN, 265 
CE. PTO, 265 
CE. RLSDTO, 265 
CE. RXOVER, 265 
CE_ RXPARITY, 265 
CE TXFULL, 265 
CF. BITMAP, 423 
CF_. DIF, 423 
CF_ DSPBITMAP, 4 
CF_ DSPMETAFILEPICT, 423 
CF_ DSPTEXT, 423 
OF_. METAF ILEPICT, 423 
CF_ OWNERDISPLAY, 423 
CF_ PRIVATELAST, 423 
OF_SYLK, 423 
CF_ TEXT, 423 
ChangeClipboardChain, 163 
ChangeMenu, 163 
char type, 607 
Character, 116-117 
Character cell, 116, 117 
Character set, 121 
CheckDIgButton, 166 
CHECKED, 625 — 
CheckMenultem, 167 
CheckRadioButton, 168 
Child window, 31, 41-43 
ChildWindowFromPoint, 168 
Chord, 169 
Class 
background brush, 30-31 
cursor, 30 
display context, 53 
icon, 30 
menu, 3k 
name, 29 
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Class (continued) 

shared, 34 

style, 32 
ClearCommBreak, 169 
Client area 

child window, 41 

redrawing, 33 
Client ToScreen, 170 
Clipboard 

defined, 3 

functions, 79 

messages, 506-507 
CLIPCAPS, 271 
ClipCursor, 170 
Clipping functions, 108 
Clipping region, default, 52 
CloseClipboard, 171 
CloseComm, 171 
CloseMetaF ile, 171 
CloseSound, 172 
CloseWindow, 172 
CLRDTR, 239 
CLRRTS, 239 
Color 

background, 99 

text, 99 

value, 97-98 
COLOR_ ACTIVEBORDER, 449 
COLOR_ ACTIVECAPTION, 31, 449 
COLOR_ APPWORKSPACE, 31, 449 
COLOR BACKGROUND, 31, 449 
COLOR. CAPTIONTEXT, 31, 449 
COLOR_ INACTIVEBORDER, 449 
COLOR. INACTIVECAPTION, 31, 

‘449 
COLOR_ MENU, 31, 449 
COLOR_ MENUTEXT, 31, 449 
COLOR_ SCROLLBAR, 31, 449 
COLOR... WINDOW, 31, 449 
COLOR_ WINDOWFRAME, 31, 449 
COLOR_ WINDOWTEXT, 31, 449 
COLORONCOLOR, 447 
CombineRgn, 173 
Common display context, 51-52 
Communication functions, 141 
COMPLEXREGION, 173, 240, 241, 
263, 315, 340, 379, 380, 412 

COMSTAT, 611 
Constrained mapping modes, 101 
Control 

description, 70 

identifier, 70 

messages, 508 

style, 71 
Convention 

naming, 8 


Convention (continued) 
notational, 12 
Coordinate functions, 106 
CopyMetaF ile, 174 
CopyRect, 174 
CountClipboardF ormats, 174 
CountVoiceNotes, 175 
CreateBitmap, 175 
CreateBitmap Indirect, 176 
CreateBrushIndirect, 176 
CreateCaret, 177 
CreateCompatibleBitmap, 178 
CreateCompatibleDC, 178 
CreateDC, 179 
CreateDialog, 180 
CreateDialog function, 65 
CreateDialogIndirect, 182 
CreateDiscardableBitmap, 184 
CreateHllipticRgn, 184 
CreateEllipticRen Indirect, 185 
CreateFont, 185 
CreateFontindirect, 188 
CreateHatchBrush, 189 
CreateIC, 189 
CreateMenu, 190 
CreateMetaF’ ile, 191 
CreatePatternBrush, 191 
CreatePen, 192 
CreatePenIndirect, 193 
CreatePolygonRen, 193 
CreateRectRgn, 194 
CreateRectRgnIndirect, 194 
CreateSolidBrush, 195 
CREATESTRUCT, 612 
CreateWindow, 195 
CreateWindow function, 40-41 
CS_. BYTEALIGNCLIENT, 634 
CS_. BYTEALIGNWINDOW, 634 
CS. CLASSDC, 53, 634 
CS. DBLCLKS, 634 
CS. HREDRAW, 634 
CS... NOCLOSE, 634 
CS_ OEMCHARS, 635 
CS_ OWNDGC, 33, 53, 635 
CS. PARENTDC, 635 


CTLCOLOR_ BTN, 555 
CTLCOLOR_ DLG, 555. 
CTLCOLOR_EDIT, 555, 
CTLCOLORW LISTBOX, 555 
CTLCOLOR_ MSGBOX, 555 
CTLCOLOR_ SCROLLBAR, 555 
CTLCOLOR_ STATIC, 555 
CtsTimeout, 615 

Cursor, 82-83 


Index 


Cursor functions, 82 
CURVECAPS, 271 


Custom cursor, 82 


Data interchange, 3 
Data types, ene conventions, 608 
DCB, 6 
Defanlt 

mapping mode, 105 

message processor, 38 

pen, 109-110 
DEFAULT_ QUALITY, 622 
DefHookProc, 206 
DefWindowProc, 206 
DeleteAtom, 207 
DeleteDC, 208 
DeleteMetaF ile, 208 
DeleteObject, 208 
DestroyCaret, 209 
DestroyMenu, 210 
Destroy Window, 210 
Destroy Window function, 45, 66 
Device context, 91-93 
Device-context attributes, 92-93 
Device-context functions, ’91 
DEVICEDATA, 683 
DEVICE_ DEFAULT. FONT, 302 
Device-independent graphics, 3 
Dialog box 

buttons, 71 

controls, 70 

creating, 65 

defined, 5, 65 

edit controls, 72 

input function, 65 

keyboard interface, 67-69 

messages, 73 

modal, 65, 67 

modeless, 66 

return values, 69-70 

scrolling, 69 

system-modal, 67 

template, 65, 66 
Dialog functions, 64-65 
DialogBox, 211 
DialogBox function, 65 
DialogBoxIndirect, 212 
Digitized aspect, 122 
Directory listing, 72 
DispatchMessage, 214 
Display context, 33-34, 51-55 
Display-context. cache, 55 
Display functions, 47 
DKGRAY_ BRUSH, 302 
DLGC_ DEFPUSHBUTTON, 561 
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DLGC.. HASSETSEL, 561 
DLGC_ PUSHBUTTON, 561 
DLGC_ RADIOBUTTON, 561 
DLGC_ WANTALLKEYS, 561 
DLGC_ WANTARROWS, 561 
DLGC. WANTCHARS, 561 
DLGC_ WANTMESSAGE, 561 
DLGC_ WANTTAB, 561 
DigDirList, 215 
DigDirSelect, 217 
DLGTEMPLATE, 617 
DM_. GETDEFID, 526 
DM_ SETDEFID, 526 
Double brackets, 12 
Double-click mouse message, 33 
DPtoLP, 217 
DRAFT... QUALITY, 622 
DRAFTMODE, 684 
Draw text control characters, 62 
Drawlcon, 218 
Drawing 

formatted text, 60 

gray text, 62 

icons, 59 

tools, 95 
Drawing-attribute functions, 98 
Drawing mode, 52 
Drawing-tool functions, 94-95 
DrawMenuBar, 219 
DRAWPATTERNRECT, 684 
DrawText, 219 
DRIVERVERSION, 270 
DsrTimeout, 615 
DSTINVERT, 159 
DT_ BOTTOM, 220 
DT. CALCRECT, aan 
DT_ EXPANDTABS, 2 
DT_ EXTERNALLEADING, 220 
DT_ NOCLIP, 220 
DT_ NOPREFIX, 221 
DT_ SINGLELINE, 221 
DT_ TABSTOP, 221 
DT... TOP, 221 
DT. VCENTER, 221 
DT_ WORDBREAK, 221 
dtCaptionText, 618 
dtClassName, 618 
dtCX, 617 
dtCY, 617 
dtilCS, 618 
dtilCY, 618 
dtilID, 618 
dtillnfo, 618 
dtilStyle, 618 
dtilText, 618 
dtilX, 618 
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dtilY, 618 
dtIltemCount, 617 
dtResourceName, 618 
dtStyle, 617 

dtX, 617 

dtY, 617 

DWORD type, 607 
Dynamic linking, 3, 4 


EDIT, 198 

Edit control, 72 

Edit-control messages, 508-510 
Edit-control notification codes, 511-512 
Ellipse, 222 

Ellipse function, 110-111 
EM_ CANUNDO, 527 

EM. FMTLINES, 527 

EM_ GETHANDLE, 528 
EM_ GETLINE, 528 

EM_ GETLINECOUNT, 529 
EM_ GETMODIFY, 529 
EM_ GETRECT, 530 

EM_ GETSEL, 530 

EM_ GETTHUMB, 533 

EM_ LIMITTEXT, 530 

EM_ LINEFROMCHAR, 531 
EM_ LINEINDEX, 531 

EM_ LINELENGTH, 532 
EM_. LINESCROLL, 533 
EM_ REPLACESEL, 533 


EM. SCROLL, 533 eae 


EM. SETHANDLE, 534 

EM.. SETMODIPFY, 535 

EM. SETRECT, 535 

EM_ SETRECTNP, 535 

EM_ SETSEL, 536 

EM. SETWORDBREAK, 536 
EM. UNDO, 537 
EEmptyClpboard, 222 

EN_ CHANGE, 511, 538 

EN ERRSPACE, 511, 538 
EN_HSCROLL, 512, 539 
EN_ KILLFOCUS, 512, 539 
EN_ SETFOCUS, 512, 539 
EN UPDATE, 540 

EN_ VSCROLL, 512, 540 
ENABLEDUPLEX, 686 
EnableHardwarelnput, 223 
EnableMenultem, 223 
ENABLEPAIRKERNING, 686 
ENABLERELATIVEWIDTHS, 687 
EnableWindow, 224 

END, 625 

EndDialog, 225 

ENDDOC, 688 


EndPaint, 226 

EnumChildWindows, 226 

EnumChipboardFormats, 228 

EnumFonts, 228 

EFnumMetaF ile, 230 

EnumObjects, 231 

EnumProps, 233 

EnumTask Windows, 235 

EnumWindows, 236 

Environment functions, 134 

EofChar, 616 

EqualRect, 337 

EqualRgn, 237 

ERROR, 173, 240, 241, 263, 315, 
340, 379, 380, 412 

Error functions, 80 

ES. AUTOHSCROLL, 202 

ES. AUTOVSCROLL, 202 

ES. CENTER, 202 . 

ES_ LEFT, 202 

ES — MULTILINE, 202 

ES— NOHIDESEL, 203 

ES... RIGHT, 203 

Escape, 238 

EscapeCommF unction, 238 

EV. BREAK, 425 

EV_ CTS, 425 

EV_ DSR, 425 

EV_ ERR, 425 

EV_PERR, 425 

EV. RING, 425 

EV_RLSD, 425 

E;V_ RXCHAR, 425 

EV_ RXFLAG, 425 

EV_ TXEMPTY, 425 

EVENPARITY, 614 

EvtChar, 617 

Examining messages, 25 

ExcludeChpRect, 239 

ExcludeUpdateRgn, 240 

Extents, 52 

External leading, 119-120 

ExtTextOut, 241 

EXTTEXTOUT, 689 


Far pointer, 10 

FAR type, 607 
FARPROC type, 607 
FatalExit, 243 
fBinary, 615 

fChEvt, 616 
fCtsHold, 611 
fDsrHold, 611 
fDtrDisable, 615 
{DtrFlow, 616 
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Features, Windows, 3-4 
fEof, 612 
fErase, 629 
FF. DECORATIVE, 623 
FF. DONTCARE, 623 
FF_ MODERN, 623 
FF_ ROMAN, 623 
FF_SCRIPT, 623 
FF_SWISS, 623 
File I/O functions, 143 
FillRect, 243 
FillRgn, 244 
Filter function, installing, 85 
Filter-function chain, 84 
FindAtom, 244 
FindResource, 245 
FindWindow, 246 
finX, 616 
FixedDisk, 628 
fixed-pitch font, 122 
Flash Window, 247 
FloodF ull, 247 
FlushComm, 248 
FLUSHOUTPUT, 690 
fNull, 616. 
Font 

default, 52 

family, 114-116 

files, 126 

functions, 113-114 

mapper, 124 

pitch, 122 

resources, 126 

selecting, 123, 125-126 
Formatted text, drawing, 60 
fOutX, 615 
fOutxDsrF low, 615 
fPeChar, 616 
FrameRect, 249 
FrameRgn, 249 
FreeLibrary, 250 
FreeProcInstance, 250 
FreeResource, 251 
fRisdHold, 611 
fRtsFlow, 616 
fTxim, 612 
Function See specific function 


GCL_ MENUNAME, 258, 420 

GCL_ WNDPROC, 258, 420 
GCW_CBCLSEXTRA, 260, 421 
GCW_ CBWNDEXTRA, 260, 421 
GCW_HBRBACKGROUND, 260, 421 
GCW_HCURSOR, 260, 421 
GCW_HICON, 260, 421 
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GCOW_HMODULE, 260, 421 
GCW_ STYLE, 260, 421 
GDI (Graphics ‘Device Interface), 3 
6-7, 123 
Generating messages, 22-23 
GetActiveWindow, 252 
GetAspectRatioF ilter, 252 
GetAsyncKeyState, 252 
GetAtomHandle, 253 
GetAtomName, 253 
GetBitmapBits, 254 
GetBitmapDimension, 254 
GetBkColor, 255 
GetBkMode, 255 
GetBrushOrg, 255 
GetBValue, 256 
GetCapture, 256 | 
GetCaretBlink Time, 257 
GetCaretPos, 257 
GetCharWidth, 257 
GetClassLong, 258 
GetClassName, 259 
GetClassWord, 259 
GetClhientRect, 260 
GetClipboardData, 261 
GetClipboardFormatName, 262 
GetClipboardOwner, 262 
GetClipboard Viewer, 263 
GetClipBox, 263 
GetCodeHandle, 264 
GETCOLORTABLE, 691 
GetCommError, 264 
GetCommEventMask, 266 
GetCommState, 266 
GetCurrentPosition, 267 
GetCurrentTask, 267 
GetCurrent Time, 267 
GetCursorPos, 268 
GetDC, 268 
GetDCOrg, 269 
GetDeviceCaps, 269 
GetDigltem, 274 
GetDlgltemInt, 274 
GetDlgltemText, 275 
GetDoubleClickTime, 276 
GetEnvironment, 276 
GETEXTENDEDTEXTMETRICS, 691 
GETEXTENTTABLE, 692 
GetFocus, 277 
GetGValue, 277 
GetInputState, 277 
GetInstanceData, 278 
GetKeyboardState, 278 
GetKeyState, 279 
GetMapMode, 282 
GetMenu, 282 
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GetMenultemCount, 282 
GetMenultemID, 283 
GetMenuState, 283 
GetMenuString, 284 
GetMessage, 285 
GetMessagePos, 286 
GetMessageTime, 287 
GetMetaF ile, 287 
GetMetaFileBits, 288 
GetModuleFileName, 288 
GetModuleHandle, 289 
GetModuleUsage, 289 
GetNearestColor, 289 
GetNextDlgGroupItem, 290 
GetNextDlgTabItem, 290 
GetNext Window, 291 
GetNumTasks, 292 
GetObject, 292 

tee beiaar ia 693 
GetParent, 293 
GETPHYSPAGESIZE, 694 
GetPixel, 293 
GetPolyFillMode, 294 
GETPRINTINGOFFSET, 694 
GetProcAddress, 295 
GetProfileInt, 295 
GetProfileString, 296 
GetProp, 297 

GetRelAbs, 298 

GetROP2, 299 

GetRValue, 299 
GETSCALINGFACTOR, 695 
GetScrollPos, 300 
GetScrollRange, 300 
GetStockObject, 301 
GetStretchBltMode, 303 
GetSubMenu, 303 
GetSysColor, 303 
GetSysModalWindow, 304 
GetSystemMenu, 304 
GetSystemMetrics, 305 
GetTempDrive, 307 
GetTempF ileName, 308 
GetTextAlign, 309 
GetTextCharacterExtra, 310 
GetTextColor, 310 
GetTextExtent, 310 
GetTextFace, 311 
GetTextMetrics, 311 
GetThresholdEvent, 312 
GetThresholdStatus, 312 
GetTickCount, 313 

Get Top Window, 313 
GETTRACKKERNTABLE, 695 
GetUpdateRect, 313 
GetUpdateRgn, 314 


GetVersion, 315 

Get ViewportExt, 315 

Get ViewportOrg, 316 

Get Window, 316 
GetWindowDC, 317 

Get WindowExt, 318 

Get WindowLong, 318 

Get WindowOrg, 319 
GetWindowRect, 319 

Get WindowTask, 319 

Get WindowText, 320 

Get WindowTextLength, 321 
GetWindowWord, 321 
Global memory, 136 
GlobalAddAtom, 322 
GlobalAlloc, 322 
GlobalCompact, 324 
GlobalDeleteAtom, 325 
GlobalDiscard, 325 
GlobalFindAtom, 326 
GlobalF lags, 326 
GlobalFree, 327 
GlobalGetAtomName, 327 
GlobalHandle, 328 
GLOBALHANDLE type, 607 
GlobalLock, 328 
GlobalReAlloc, 329 
GlobalSize, 331 
GlobalUnlock, 331 
GlobalUn Wire, 332 
GlobalWire, 332 

GMEM_ DDESHARE, 323, 327 


GMEM_ DISCARDABLE, 323, 327, 329 


GMEM_ DISCARDED, 327 

GMEM_ FIXED, 323 

GMEM_ MODIFY, 329 

GMEM_. MOVEABLE, 323, 330 

GMEM_ NOCOMPACT, 323, 330 

GMEM_ NODISCARD, 393, 330 

GMEM_ NOT_ BANKED, 393, 327 

GMEM_ NOTIFY, 324 

GMEM_ ZEROINIT, 324, 330 

Graphics device interface function 
groups, 7, 91 

erepoics device interface (GDI), 3, 6-7, 


GRAY. BRUSH, 302 
Gray text, drawing 62-63 
GRAYED, 6 25 
nig trin ae 332 
CHIPD, 3 


GW_HWNDFIRST. 316 
GW_HWNDLAST, 316 
GW_HWNDNEXT, 291, 317 
GW_HWNDPREV, 291, 317 
GW_ OWNER, 317 


Index 


GWL_STYLE, 318, 463 
GWL_ WNDPROG, 318, 463 
GWW_HINSTANCE, 321, 475 
GWW_HWNDPARENT, 321, 475 
GWW_HWNDTEXT, 321 
GWW_ ID, 321, 475 


HANDLE type, 607 
HANDLETABLE, 619 
Hardware functions, 49 
Hatched brush patterns, 96 
HBITMAP type, 607 
hbrBackground, 636 
HBRUSH type, 608 
hCursor, 635 
HCURSOR type, 608 
HDC type, 608 
HELP, 625 
Helvetica typeface, 114 
HFONT type, 608 
HIBYTE, 335 
hIcon, 635 
HICON type, 608 
HideCaret, 335 
Hiding 

cursor, 83 

scroll bar, 76 
HiliteMenultem, 335 
hInstance, 635 
HIWORD, 337 
HMENU type, 608 
hMF’, 627 
HOLLOW_ BRUSH, 302 
Hook functions, 84 
HORZRES, 270 
HORZSIZE, 270 
HPEN type, 608: 
HRGN type, 608 
HS_ BDIAGONAL, 189, 620 
HS_ CROSS, 189, 620 
HS_ DIAGCROSS, 189, 620 
Hs. FDIAGONAL, 189, 620 
HS_ HORIZONTAL, 189, 620 
HS_ VERTICAL, 189, 620 
HSTR type, 608 
HTBOTTOM, 578 
HTBOTTOMLEFT, 578 
HTBOTTOMRIGHT, 578 
HTCAPTION, 578 
HTCLIENT, 578 
HTERROR, 578 
HTGROWBOX, 578 
HTHSCROLL, 579 
HTLEFT, 578 
HTMENU, 578 
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HTNOWHERE, 578 
_ HTREDUCE, 578 
HTRIGHT, 579 
HTSIZE, 579 
HTSYSMENU, 579 
HTTOP, 579 
HTTOPLEFT, 579 
HTTOPRIGHT, 579 
HTTRANSPARENT, 579 
HTVSCROLL, 579 
HTZOOM, 579 


Icon 
class, 30 
drawing, 59 
Id, 614 
IDABORT, 374 
IDC_ ARROW, 353 
IDC. CROSS, 353 
IDC_ IBEAM, 353 
IDC_ ICON, 353 


374 
IDL APPLICATION, 354 
IDL. ASTERISK, 354 
IDL EXCLAMATION, 354 
IDL. HAND, 3 
IDI QUESTION, 304 
IDIGNORE, 374 
IDNO, 374 
IDOK, 374 
IDRETRY, 374 
IDYES, 374 
TE.. BADID, 382 
IE. BAUDRATE, 382 
TE. BYTESIZE, 382 
TE_ DEFAULT, 382 
IE_ HARDWARE, 382 
JE_ MEMORY, 382 
IE_ NOPEN, 382 
IE_ OPEN, 382 
INACTIVE, 625 
IncUpdate, 629 
InflateRect, 338 
Information context, 94 
Information functions, 78 
InitAtomTable, 338 


Initialization-file functions, 140 


Initialization messages, 503 
Input functions, 48 

Input messages, "503-504 
InSendMessage, 339 
Installing filter function, 85 
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Instance handle, 29 

int type, 608 

Integer messages, 517 
Intercharacter spacing, default, 52 
Internal data structure, 46 
Internal leading, 119-120 
IntersectClipRect, 339 
IntersectRect, 340 
InvalidateRect, 341 
InvalidateRgn, 342 
InvertRect, 343 
InvertRgn, 343 

IsChild, 344 
IsClipboardFormatAvailable, 344 
IsDialogMessage, 345 
IsDlgButtonChecked, 345 
IsIconic, 346 
IsRectEmpty, 346 

Is Window, 347 
IsWindowEmabled, 347 
IsWindowVisible, 347 
IsZoomed, 348 

Italic font, 117 

Italic type, 12 


Keyboard, 3, 68 
Keyboard input, 23 


KillTimer, 349 


LB.. ADDSTRING, 541 
LBL Ree 541 
LB... DIR, 5 

LB. GETCOUNT. 542 

LB_ GETCURSEL, 542 
LB. GETSEL, 543 

LB. GETTEXT, 543 

LB. GETTEXTLEN, 544 
LB_INSERTSTRING, 544 
LB. RESETCONTENT, 544 
LB_ SELECTSTRING, 545 
LB. SETCURSEL, 545 
LB_SETSEL, 546 

IbColor, 619 

IbHatch, 619 

LBN. DBLCLK, 512, 546. 
LBN_ ERRSPACE, 512, 547 
LBN.. SELCHANGE, 512, 547 
LBS — MULTIPLESEL, 204 
LBS. NOREDRAW, 204 
LBS. NOTIFY, 204 

LBS_ SORT, 204 

LBS_ STANDARD, 204 
IbStyle, 619 

Leading, 119-120 


left, 630 
IfCharSet, 622 
IfClipPrecision, 622 
lfEscapement, 621 
lfFaceName, 624 
IfHeight, 621 
lfItalic, 621 
lf Orientation, 621 
lfOutPrecision, 622 
lfPitchAndF amily, 623 
lfQuality, 622 
lIfStrikeOut, 621 
IfUnderline, 621 
IfWeight, 621 
IfWidth, 621 
Library, 3-4 
Life cycle, 44-46 
Line-output functions, 108 
LINECAPS, 272 
LineDDA, 350 
LineTo, 351 
List-box 
control, 72 
messages, 510 
notification codes, 512 
LISTBOX, 198 
LMEM_ DISCARDABLE, ie 360, 364 
LMEM_ DISCARDED, 360 
LMEM_ FIXED, 358 
LMEM_. MODIFY, 358, 364 
LMEM_ MOVEABLE, 358, 365 
LMEM_ NOCOMPACT, 358, 365 
LMEM_ NODISCARD, 358, 365 
LMEM_ ZEROINIT, 358, 365 
LoadAccelerators, 351 
LoadBitmap, 352. 
LoadCursor, 353 
LoadIcon, 354 
LoadLibrary, 355 
LoadMenu, 355 
LoadMenulndirect, 356 
LoadResource, 356 
LoadString, 357 
LOBYTE, 357 
Local memory, 136 
LocalAlloc, 358 
LocalCompact, 359 
LocalDiscard, 359 
LocalF lags, 360 
LocalF ree, 360 
LocalF reeze, 361 
LocalHandle, 361 
LOCALHANDLE type, 608 
LocalHandleDelta, 361 
LocallInit, 362 
LocalLock, 362 


Index 


LocalMelt, 363 
LocalNotify, 363 
LocalReAlloc, 364 
LocalShrink, 366 
LocalSize, 366 
LocalUnlock, 367 
LockData, 367 
LockResource, 368 
LockSegment, 368 
LOGBRUSH, 619 
LOGFONT, 620 
Logical units, 109 
LOGPEN, 624 
LOGPIXELSX, 270 
LOGPIXELSY, 270 
long type, 608 
LONG type, 608 
lopnColor, 624 
lopnStyle, 624 

lopn Width, 624 
LOWORD, 369 
lParam, 627 

Ipfn WndProc, 635 
LPINT type, 608 
LPMSG type, 608 
LPRECT type, 608 
LPSTR type, 608 
IpszClassName, 636 
IpszMenuName, 636 
LPtoDP, 369 
LTGRAY_ BRUSH, 302 


MAKEINTATOM, 370 
MAKEINTRESOURCE, 370 
MAKELONG, 370 
MAKEPOINT, 371 
MakeProcInstance, 371 
MapDialogRect, 372 

Mapping functions, 99-100 
Mapping modes, 52, 101-106 
MARKPARITY, 614 

max, 373 

Maximum character width, 122 
MB_ ABORTRETRYIGNORE, 375 
MB_ APPLMODAL, 375 
MB_DEFBUTTON1, 375 
MB_ DEFBUTTON2, 375 
MB. DEFBUTTONS, 375 
MB_ICONASTERISK, 375 
MB_ICONEXCLAMATION, 375 
MB_ ICONHAND, 375 
MB_ICONQUESTION, 375 
MB_ OK, 375 

MB. OKCANCEL, 375 

MB_ RETRYCANCEL, 375 
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MB. SYSTEMMODAL, 375 

MB_ YESNO, 375 

MB_ YESNOCANCEL, 375 
Memory, 3 

Memory-manager functions, 136-137 
Menu, 5, 31, 44 

Menu functions, 77 


MENUITEMTEMPLA TE, 625 

MERGECOPY, 159 

MERGEPAINT, 159 

Message, 6, 21- 25, 37-38, 627 
See also specific message 

Message functions, 21-22 

MessageBeep, 373 

MessageBox, 373 

Metafile, 127-129 

Metafile functions, 127 

METAFILEPICT, 626 

MF_. APPEND, 165 

MF_ BITMAP, 165, 574 

MF. B COMMAND, 165, 167, 224, 336 

MF_ BYPOSITION 165, 187, 924, 336 

MF_ CHANGE, 1 

MF_ CHECKED, 185, 167, 284, 574 

MF_ DELETE, 165 

MF_. DISABLED, 165, 224, 284, 574 

MF_ ENABLED, 165, 294, 984 

MF_ GRAYED, 165, 224, 574 

MF_ HELP, 574 

MF_ HILITE, 336 

MF_INSERT, 165 

MF_ MENUBARBREAK, 165, 284 

MF_ MENUBREAK, 166, 284 

MF_ MOUSESELECT, 574 

MF_. POPUP, 166, aie 

MF_ REMOVE, 166 

MF_ SEPARATOR, 166, 284 

MF_STRING, er 

MF. SYSMENU, 5 

MF UNCHECKED, 166, 167, 284 

MF_. UNHILITE, 3 

MEF COMMENT, 698 

min, 376 

ae Se 569, 570, 571, 572, 

5, 588 

MK-LBUTTON, 569, 571, 572, 575, 
588 

MK_MBUTTON, 569, 570, 571, 575, 
288 

Mic RBUTTON, 569, 570, 571, 572, 
5 

MK_ SHIFT, 569, 570, 571, 572, 575, 
588, 589 

mm, 626 
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MM_ ANISOTROPIC, 432 
MM_ HIE-NGLISH, 432 
MM_ HIMETRIC, 432 
MM_ ISOTROPIC, 432 
MM. LOENGLISH, 432 
MM_LOMETRIC, 432 
MM_ TEXT, 432 

MM_ TWIPS, 432 

Modal dialog box, 67 


ode 
background, 99 
default mapping, 105 
mapping, 101-106 
stretch, 99 
Modeless dialog box, 66 
Module-manager functions, 135 
Monospace type, 12 
Mouse, 3, 82 
Mouse cursor See Cursor 
Movement functions, 47 
MoveTo, 376 
MoveWindow, 377 
MS-DOS Executive, 41, 64 
MSG, 627 
MSGF_ Me yi A74 
MSGF_ MENU, 473 
MSGF_MESSAGEBOX. 473, 474 
mtID, 626 
mtOption, 625 
mtString, 626 
Multitasking, 3, 4 


Naming 
conventions, 8, 608 
parameters, 9 
Near pointer, 10 
NEAR type, 608 
nErrCode, 628 
NEWFRAME,, 696 
NEXTBAND, 697 
Non-client area 
messages, 513-514 
painting, 58 
NOPARITY, 614 
Notational convention, 12 
Notification codes, 511-512 
Notification messages, 511 
NULL_ BRUSH, 302 
NULL PEN, 302 
NULLREGION, 173, 240, 241, 263, 
315, 340, 379, 380, 412 
NUMBRUSHES, 270 
NUMCOLORS, 270 
NUMFONTS, 270 
NUMPENS, 270 


objectHandle, 619 
ODDPARITY, 614 
OEM character set, 122 
OEM_ FIXED_ F ONT, 302 
OemToAnsi, 378 

OF_. CANCEL, 383 
OF_ CREATE, 383 
OF_ DELETE, 383 
OF_ EXIST, 383 

OF_ PARSE, 383 

OF_ PROMPT, 383 


OF_ VERIFY, 384 
OF_ WRITE, 384 
OffsetClipRgn, 378 
OffsetRect, 379 
OfisetRgn, 380 

Offset ViewportOrg, 380 
Offset WindowOrg, 381 
OFSTRUCT, 628 
ONESSTOPBITS, 614 
ONESTOPBIT, 614 
OPAQUE, 417 
OpenClipboard, 381 
OpenComm, 382 
OpenFile, 383 
Openlcon, 384 
OpenSound, 385 
Output, 131-132 
OutxCtsFlow, 615 
Overhang, 123 
Overlapped window, 39-40 


Painting 
functions, 49-50 
non-client area, 58 
rectangles, 58 
sequence, 55 
system display, 50 
PaintRgn, 386 
PAINTSTRUCT, 628 
Parameter naming, 9 
Parent window, 41-43 
Parentheses (()), 12 
Parity, 614, 615 


Partially constrained mapping 


modes, 102-103 
PatBlt, 386 
PATCOPY, 159 
PATINVERT, 159 
PATPAINT, 159 
PDEVICESIZE, 271 
PeChar, 616 
PeekMessage, 387 


Index 


Pen, 52, 96-97, 109-110 


le, 3 
PINT type, 608 
Pitch, 122 
PLANES, 270 
PlayMetaF ile, 390 
PlayMetaFileRecord, 391 
Plotter, 3 
PM_ NOREMOVE, 388 
PM_ NOYIELD, 388 
PM_ REMOVE, 388 
POINT, 629 
Pointing oe 82 
Polygon, 3 
Polygon-filling mode, default, 52 
Polygon function, 110-111 
POLYGONALCAPS, 272 
Polyline, 392 
POPUP, 625 
Pop-up window, 40-41 
PostAppMessage, 393 
Posting messages, 25 
PostMessage, 393 
PostQuitMessage, 394 
Predefined 

brushes, 95 

pens, 96-97 

window class, 34-35 
Printer-escape functions, 130-131 
Printer escapes, 681-708 
Printing, 133 
Private display context, 53-54 
Processing messages, 22-23 
PROOF_ QUALITY, 622 
Property functions, 86 
Property list, 86-87 
PSTR type, 608 

pt, 627 
PiinRect, 395 
PtInRegion, 395 
PtVisible, 396 - 


QUERYESCSUPPORT, 698 
Queue, 22, 25 
QUEUEEMPTY, 496 


R2_ BLACK, 666, 667 

R2_ COPYPEN, 666, 667 

R2_ MASKNOTPEN, 443, 666, 667 
R2_. MASKPEN, 443, 666, ‘667, 668 
R2_ MASKPENNOT, 443, 666, 667, 


R2- MERGENOTPEN, 443, 666, 667, 
668 
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R2_MERGEPEN, 443, 666, 667, 668 
R2_MERGEPENNOT, 443, 666, 667, 


668 
R2_ NOP, 666, 667, 668 
R2_ NOT, 443, 666, 667, 668 
R2_ NOTOOPYPEN, 443, 666, 667, 


R2_ NOTMASKPEN, 443, 666, 667, 
668 

R2_ NOTMERGEPEN, 443, 666, 667, 
668 


R2.. NOTXORPEN, 443, 666, 667, 668 
R2_ WHITE, 666, 667, 668 
R2_ XORPEN, 443, 666, 667, 668 
RASTERCAPS, 271 | 
RC_ BANDING, 271 
RC_BITBLT, ee 
RCL BITMAP64, 2 
RC_. GDI20_ OUTPUT, 271 
RC.. SCALING, 271 
rcPaint, 629 
ReadComm, 397 
RECT, 630 
Rectangle 

bounding, 111 

coordinates, 88-90 

drawing, 397 

functions, 88 

painting, 58 

use of, 88 

validating, 493 
Rect Visible, 398 
Redrawing client area, 33 
Region functions, 107 
Region, 494 
RegisterClass, 398 
RegisterClipboardFormat, 400 
RegisterWindowMessage, 400 
RELATIVE, 440 
Relative-absolute flag, 52 
ReleaseCapture, 401 
ReleaseDC, 401 
RemoveFontResource, 402 
RemoveProp, 403 
ReplyMessage, 403 
reserved, 628 
Reserved messages, 517 
RESETDEV, 239 
Resource, 138 
Resource-manager functions, 138 
Restore, 629 
RestoreDC, 404 
Return value, dialog box, 69 
RGB, 405, 630 
RGB color value, 97-98 
rgbReserved, 629 
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RGN_ AND, 173 
RGN. COPY, 173 
RGN_ DIFF’, 173 
RGN_ OR, 173 
RGN_XOR, 173 
right, 630 
RlsTimeout, 615 
RoundRect, 405 
RT_ ACCELERATOR, 245 
RT_ BITMAP, 245 
RT_ CURSOR, 245 
RT. DIALOG, 245 
RT_ FONT, 245 


RT_ RCDATA, 245 
RT_STRING, 245 
RtsDisable, 615 


S..LEGATO, 458 

S_ NORMAL, 458 

S_ PERIOD 1024, 446 

S_ PERIOD 2048, 446 

S_ PERIOD512, 446 

S._ PERIODVOICE, 446 

S_.SERDCC, 460 

S_SERDDR, 461 

S_ SERDFQ, 461 

S_ SERDLN, 460 

S_SERDMD, 458 

S_SERDNT, 460 

S_SERDRC, 459 

S_SERDSH, 459 

S_SERDTP, 458 

S_SERDVL, 458, 461 

S_..SERMACT, 460 

S_ SEROFM, 460 

S_SERQFUL, 458, 459, 460, 461 

S_ STACCATO, 458 

S_ WHITE1024, 446 

S— WHITE2048, 446 

S— WHITE512, 446 

S_ WHITEVOICE, 446 

SaveDC, 407 

SB BOTH, 478 

SB BOTTOM. 564, 565, 602, 603 

SB_ CTL, 300, 301, ‘444, ‘445, ‘478 

SB_ ENDSCROLL, 564, 565, 602, 603 — 

SB..HORZ, 300, 301, 444, 445, 478 “3 

SB_ LINEDOWN, 533, 564, 565, 602, 
603 

SB_ LINEUP, 534, 564, 565, 602, 603 

SB..PAGEDOWN, 534, 564, 565, 602, 


603 
SB_PAGEUP, 534, 564, 565, 602, 603 


SB_ aa ee 534, 564, 565, 


SB THUMBTRACK, 564, 602 
SB_ TOP, 564, 565, 602, 603 

SB_. VERT, 300, 301, 444, 445, 478 
SBS_— BOTTOMALIGN, 204 
SBS— HORZ, 204 

SBS_ LEFTALIGN, 204 

SBS_ SRR he 205 

SBS_ SIZEBOX, 2 


SBS. SIZEBOXBOTTOMRIGHTALIGN, 


205 
SBS. SIZEBOXTOPLEFTALIGN, 205 
SBS_ TOPALIGN, 205 
SBS_ VERT, 205 
ScaleViewportExt, 407 
ScaleWindowExt, 408 
SC... CLOSE, 596 
eg HSCROLL, 596 


SC_MOUSEMENU, 596 
SC_ MOVE, 597 
SC_. NEXTWINDOW, 597 


SC_ VSCROLL, 597 
ScreenToClient, 408 
Scroll bar 

control, 74 

description, 43-44 

hiding, 76 

messages, 512 

thumb, 75-76 
SCROLLBAR, 198 
ScrollIDC, 409 
Scrolling 

dialog boxes, 69 

functions, 73 

procedure, 75 

request, 74 
ScrollWindow, 410 
SelectClipRgn, 411 
Selecting fonts, 123, 125-126 
SelectObject, 412 
SendDlgltemMessage, 414 
SendMessage, 414 
Serif typeface, 115 
SETABORTPROC, 698 
SetActiveWindow, 415 
SETALLJUSTVALUES, 699 
SetBitmapBits, 416 
SetBitmapDimension, 416 
SetBkColor, 416 


SetBkMode, 417 
SetBrushOrg, 418 
SetCapture, 418 
SetCaretBlink Time, 419 
SetCaretPos, 419 
SetClassLong, 420 
SetClassWord, 421 
SetClipboardData, 422 
SetClipboard Viewer, 424 
SETCOLORTABLE, 701 
SetCommbBreak, 424 
SetCommEventMask, 425 
SetCommState, 426 
SETCOPYCOUNT, 702 
SetCursor, 426 
SetCursorPos, 427 
SetDigltemInt, 427 
SetDlgItemText, 428 
SetDoubleClickTime, 429 
SETDTR, 239 
SetEnvironment, 429 
SetFocus, 430 
SETKERNTRACK, 702 
SetKeyboardState, 431 
SETLINECAP, 703 
SETLINEJOIN, 704 
SetMapMode, 431 
SetMapperF lags, 433 
SetMenu, 433. 
SetMessageQueue, 434 
SetMetaFileBits, 434 
SETMITERLIMIT, 705 
SetParent, 435 

SetPixel, 435 
SetPolyFillMode, 436 
SetPriority, 437 
SetProp, 437 

SetRect, 438 
SetRectEmpty, 439 
SetRectRgn, 439 
SetRelAbs, 440 
SetResourceHandler, 440 
SetROP2, 442 

SETRTS, 239 
SetScrollPos, 444 
SetScrollRange, 445 
SetSoundNoise, 446 
SetStretchBltMode, 447 
SetSwapAreaSize, 448 
SetSysColors, 448 
SetSysModalWindow, 450 
SetTextAlign, 450 


Set TextCharacterExtra, 452 


Set TextColor, 452 
Set Text Justification, 453 
Set Timer, 454 
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Set ViewportExt, 455 

Set ViewportOrg, 457 

Set VoiceAccent, 457 

Set VoiceEnvelope, 459 

Set VoiceNote, 459 

Set VoiceQueueSize, 460 

Set VoiceSound, 461 

Set VoiceThreshold, 461 

Set WindowExt, 462 

SetWindowLong, 463 

Set WindowOrg, 464 

SetWindowPos, 465 

Set WindowsHook, 466 

Set Window Text, 474 

SetWindowText function, 43 

Set WindowWord, 475 

SETXOFF, 239 

SETXON, 239 

Shared display, 3 

Shared window class, 34 

short type, 608 

ShowCaret, 475 

ShowCursor, 476 

ShowOwnedPopups, 477 

ShowScrollBar, 477 

ShowWindow, 478 

Simple text processing, 60 

SIMPLEREGION, 178, 240, 241, 
263, 315, 340, 379, "380, "412 

SIZEFULLSCREEN, 593 

SIZEICONIC, 593 

SIZENORMAL, 593 

SizeofResource, 480 

SIZEZOOMHIDE, 594 

SIZEZOOMSHOW, 594 

SM_ CXBORDER, 306 

SM_ CXDLGFRAME, 306 

SM_ CXFRAME, 306 

SM_ CXFULLSCREEN, 307 

SM_: CXHSCROLL, 306 

SM_ CXHTHUMB, 306 

SM_ CXMINTRACK, 307 

SM. CXSIZE, 307 

SM. CXVSCROLL, 306 

SM_ CYBORDER, 306 

SM_ CYDLGFRAME, 306 

SM_ CYFRAME,, 306. 

SM_ CYFULLSCREEN, 307 

SM_ CYHSCROLL, 306 

SM_ CYSIZE, 307 

SM_ CYVSCROLL, 306 

SM_ CYV THUMB, 306 

SM_ DEBUG, 307 

SM. MOUSEPRESENT, 307 

SM_SWAPBUTTON, 307 

Sound functions, 142 


722 


SP_APPABORT, 697 

SP.. ERROR, 697 

SP_ OUTOFDISK, 697 

SP_ OUTOFMEMORY, 697, 698 
SP_ USERABORT, 697, 698 
SPACEPARITY, 614 
SRCAND, 158 

SRCCOPY, 158 

SRCERASE, 158 
SRCINVERT, 158 
SRCPAINT, 158 

SS.. BLACKFRAME, 203 

SS_ BLACKRECT, 203 

SS__ CENTER, 203 
SS..GRAYFRAME, 203 

SS_ GRAYRECT, 203 

SS_ ICON, 203 

SS_ LEFT, 203 

SS_ RIGHT, 203 

SS_ SIMPLE, 204 

SS_ USERITEM, 204 

SS. WHITEFRAME, 204 

SS. WHITERECT, 204 
Standard scroll bar, 74 
STARTDOC, 706 
StartSound, 480 

STATIC, 198 

StopSound, 480 

Stretch mode, 99 

StretchBlt, 481 
STRETCHBLT, 707 
Stretching mode, default, 52 
Strikeout font, 119 

String messages, 517 
String-translation functions, 139 
style, 634 

Styles, window, 39 
Subclassing, windows, 46 
SwapMouseButton, 483 

SW-_ HIDE, 479 

SW_ MINIMIZE, 4 

SW. OTHERUNZOOM, 593 
SW_ OTHERZOOM, 593 
SW_ PARENTCLOSING, 593 
SW... PAREN TOPENING, 593 
SW_ RESTORE, 479 

SW_ SHOW, 479 
SW_.SHOWMAXIMIZED, ph 
SW... SHOWMINIMIZED, 


SW. SHOWMINNOACTIVATE, 479 


SW_SHOWNA, 4 
SW_ SHOWNOACTIVATE, 479 
SW_SHOWNORMAL, 479 
SWP_DRAWFRAME, 465 
SWP_HIDEWINDOW, 465 
SWP_NOACTIVATE, 465 


SWP_ NOMOVE, 465 
SWP_ NOREDRAW, 465 
SWP.. NOSIZE, 465 
SWP_ NOZORDER, 465 
SWP_SHOWWINDOW, 465 
SyncAliVoices, 484 
System 

display, 50 

functions, 79 

hooks, 85 

menu, 43-44 

messages, 505-506 

timer, 3 
System menu, 43 
System services interface, 3,8 | 
System services interface function 

groups, 8, 135 

SYSTEM_ FONT, 302 
System-information messages, 507 
System-modal dialog box, 67 
szPathName, 628 


TA~ BASELINE, 309, 451 
TA~ BOTTOM, 309, 451 
TA. CENTER, 309, 451 
TA_ LEFT, 309, 451 
TA_ NOUPDATECP, 309, 451 
TA_ RIGHT, 309, 451 
TA TOP, 309, 451 
TA_ UPDATECP, 309, 451 
Task, 23, 137, 498 
Task functions, 137 
TECHNOLOGY, 270 
Text 
color, 52, 99 
formatting methods, 60 
functions, 113 
processing, 60 
TEXTCAPS, 273 
TEXTMETRIC, 631 
TextOut, 485 
THRESHOLD, 496 
Throw, 485 
time, 627 
Timer, 349 
Title bar, 43 
tmAscent, 631 
tmAveCharWidth, 632 
tmBreakChar, 632 
tmCharSet, 632 
tmDefaultChar, 632 
tmDescent, 631 
tmDigitizedAspectX, 633 
tmDigitizedAspectY, 633 
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tmExternalLeading, 632 
tmFirstChar, 632 

tmHeight, 631 
tmInternalLeading, 631 
tmiltalic, 632 

tmLastChar, 632 
tmMaxCharWidth, 632 
tmOverhang, 633 
tmPitchAndF amily, 632 
tmStruckOut, 632 
tmUnderlined, 632 

tmWeight, 632 

top, 630 

Transformation equations, 103-104 
TranslateAccelerator, 486 
TranslateMessage, 487 
TranslateMessage function, 23 
Translating messages, 23-24 
TransmitCommChar, 488 
TRANSPARENT, 417 
TranslateAccelerator function, 24 
TWOSTOPBITS, 614 
TxDelay, 617 

Typeface, 114 

Types, data, 607-608 


Unconstrained mapping modes, 
102-103 
Underline font, 118-119 
UngetCommChar, 489 
Unhook WindowsHook, 489 
UnionRect, 490 
UnlockData, 490 
UnlockResource, 491 
UnlockSegment, 491 
Unqueued message, 22 
UnrealizeObject, 492 
Update region, 56 
UpdateWindow, 492 
Utility functions, 143 


ValidateFreeSpaces, 493 
ValidateRect, 493 
ValidateRgn, 494 
Variable-pitch font, 122 
Vector device, 3 
VERTRES, 270 
VERTSIZE, 270 

Viewport extents, default, 52 
Viewport origin, default, 52 
Virtual-key message, 23 
Virtual keys, 23 

VOID type, 608 
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WaitMessage, 495 
WaitSoundsState, 495 

WH_ CALLWNDPROC, 466, 489 
WH. GETMESSAGE, 466, 489 


WH JOURNALPLAYBACK, 466, 489 


WH_ JOURNALRECORD, 467, 490 
WH... KEYBOARD, 85, 467, 490 
WH. MSGFILTER, 85, 467, 490 
WH_SYSMSGFILTER, 467 
WHITE_ BRUSH, 302 
WHITE_ PEN, 302 
WHITENESS, 159 
WHITEONBLACK, AAT 
WINDING, 294, 436 
Window 

background, 57 

child, 41-43 

class, 27-28 

description, 4 

dialog box, 64 

display context, 54-55 

function, 35-36 

menu, 44 

open, 40 

overlapped, 39-40 

parent, 41-43 

pop-up, 40-41 

scroll bars, 43 

styles, 39 

subclassing, 46 

system menu box, 43 

title bar, 43 
Window applications, 22-23 
Window class 

background brush, 30 

description, 27 

elements, 27-28 

menu, 31 

predefined, 34 

registering, 35 

shared, 34 

styles, 32 
Window extents, default, 52 
Window function, 23, 29 
Window manager ‘interf ace, 4-6 
Window manager interface ‘function 

groups, 6, 21 
Window origin, default, 52 
Window state, 44 
Window-creation functions, 26 
WindowFromPoint, 496 
Window-function address, 29 
Window-management messages, 
501-502 

Windows calling convention, 10 
Windows features, 3-4 


724 


WinMain, 24 

WM_ ACTIVATE, 549 
WM_ACTIVATEAPP, 550 
WM. ASKCBFORMATNAME, 550 
WM_ CANCELMODE, 551 
WM_ ace 551 
WM_ CHAR, 5 

WMA CHILBACTIVATE 552 
WM_ CLEAR, 553 

WM_ CLOSE, 45, 553 

WM.. COMMAND, 553 

WM_. COPY, 554 

WML_ CREATE, 45, 554 

WM_ CTLCOLOR, 555 

WML_ CUT, 556 

WM_ DEADCHAR, 556 

WM_ DESTROY, 45, 557 

WM_ DESTROYCLIPBOARD, 558 
WM_ DEVMODECHANGE, 558 
WM.. DRAWCLIPBOARD, 558 
WM_ ENABLE, 559 

WM.. ENDSESSION, 559 
WM_ERASEBKGND, 559 
WM_F ONTCHANGE, 560 
WM_ GETDLGCODE, 561 
WM_ GETMINMAXINEO, 562 
WM_ GETTEXT, 563 

WM_ GETTEXTLENGTH, 563 
WM... HSCROLL, 43, 564 

WM_ HSCROLLCLIPBOARD, 565 
WM_ INITDIALOG, 565 

WM_ INITMENU, 566 
WM_INITMENUPOPUP, 566 
WM_KEYDOWN, 5 

WM. KEYUP, 568 

WML_ KILLFOCUS, 569 
WM_LBUTTONDBLCLK, 569 
WM_LBUTTONDOWN, 570 
WM_LBUTTONUP, 570 
WM_MBUTTONDBLCLKE, 571 
WM_MBUTTONDOWN, 572 
WM_ MBUTTONUP, 572 

WM_ MENUCHAR, 573 

WM_ MENUSELECT, 574 
WM. MOUSEACTIVATE, 574 
WM_ MOUSEMOVE, 575 

WM_ MOVE, 576 

WM_ NCACTIVATE, 576 
WM... NCCALCSIZE, 576 

WM_ NCCREATE, 577 

WM_ NCDESTROY, 577 

WM. NCHITTEST, 578 

WM. NCLBUTTONDBLCLK, 579 
WM_ NCLBUTTONDOWN, 580 
WM_ NCLBUTTONUP, 580 
WM_ NCMBUTTONDBLCLK, 581 


WM_ NCMBUTTONDOWN, 581 
WM. NCMBUTTONUP, 582 
WM. NCMOUSEMOVE, 582 
WM_NCPAINT, 582 

WM. NCRBUTTONDBLCLK, 583 
WM.. NCRBUTTONDOWN, 583 
WM_ NCRBUTTONUP, 584 
ME DN ee 584 

WML_ PAINT, 585 

WML_ PAIN TCLIPBOARD, 585 
WML_ PASTE, 586 

WM. QUERYENDSESSION, 586 
WM. QUERYOPEN, 587 

WM_ QUIT, 46, 587 

WM_ RBUTTONDBLCLK, 587 
WM_RBUTTONDOWN, 588 
WM_RBUTTONUP, 589 

WM_ RENDERALLFORMATS, 589 
WM... RENDERFORMAT, 590 
WM_SETCURSOR, 590 

WM.. SETFOCUS, 591 
WM_SETREDRAW, 591 
WM_SETTEXT, 592 
WML_SETVISIBLE, 592 
Lee 592 
WM_ SIZE, 593 

WM. SIZBCLIPBOARD, 594 
WM. SYSCHAR, 5 

WM SYSCOLORCHANGE, 596 
WM_SYSCOMMAND, 5 

WM_ SYSDEADCHAR, 508 
WM. SYSKEYDOWN, 598 
WM_SYSKEYUP, 599 
WM_SYSTEMERROR, 600 
WM_ TIMECHANGE, 601 

WWM_ TIMER, 601 

WM_ USER, 517 
WM_VSCROLL, 43, 602 

WM_ VSCROLLCLIPBOARD, 603 
WM_ WININICHANGE, 604 
WNDCLASS, 634 

WORD type, 608 

wParam, 627 

WriteComm, 496 
WriteProfileString, 497 

WS.. BORDER, 199 

WS. CAPTION, 43, 199 

WS_ CHILD, 41, 199 

WS_ CHILDWINDOW, 199 
WS_ CLIPCHILDREN, 199 

WS-_ CLIPSIBLINGS, 199 

WS_ DISABLED, 199 

Ws_ DLGFRAME, 199 

WS_ GROUP, 199 

WS_ HSCROLL, 199 

WS_ ICONIC, 199 
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WS_ MAXIMIZE, 200 

WS_. MAXIMIZEBOX, 200 

WS_ MINIMIZE, 200 

WS_ MINIMIZEBOX, 200 

WS_ OVERLAPPED, 200 

WS_ OVERLAPPEDWINDOW, 40, 
200 

WS_ POPUP, 41, 200 

WS_ POPUPWINDOW, 200 

WS_SYSMENU, 43, 200 

WS_ TABSTOP, 200 

WS_ THICKFRAME, 200 

WS_ VISIBLE, 200 

WS_VSCROLL, 200 


xExt, 626 
XoffChar, 616 
XoffHold, 611 
XoffLim, 616 
XoffSent, 611 
XonChar, 616 
XonLim, 616 


yExt, 626 
Yield, 498 
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